idnits 2.17.1 draft-ietf-kitten-rfc2853bis-03.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 4474. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4485. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4492. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4498. 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 (August 2, 2007) is 6111 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 4013 ** 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: February 3, 2008 Sun Microsystems 6 August 2, 2007 8 Generic Security Service API Version 2 : Java Bindings Update 9 draft-ietf-kitten-rfc2853bis-03.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 February 3, 2008. 36 Copyright Notice 38 Copyright (C) The IETF Trust (2007). 40 Abstract 42 The Generic Security Services Application Program Interface (GSS-API) 43 offers application programmers uniform access to security services 44 atop a variety of underlying cryptographic mechanisms. This document 45 updates the Java bindings for the GSS-API that are specified in 46 "Generic Security Service API version 2 : Java Bindings" (RFC2853). 47 This document obsoletes RFC 2853 by making specific and incremental 48 clarifications and corrections to it in response to identification of 49 transcription errors and implementation experience. 51 The GSS-API is described at a language independent conceptual level 52 in "Generic Security Service Application Program Interface Version 2, 53 Update 1" (RFC2743). The GSS-API allows a caller application to 54 authenticate a principal identity, to delegate rights to a peer, and 55 to apply security services such as confidentiality and integrity on a 56 per-message basis. Examples of security mechanisms defined for GSS- 57 API are "The Simple Public-Key GSS-API Mechanism" (RFC2025) and "The 58 Kerberos Version 5 GSS-API Mechanism (RFC4121). 60 Table of Contents 62 1. Conventions Used in This Document . . . . . . . . . . 7 63 2. Introduction . . . . . . . . . . . . . . . . . . . . . 7 64 3. GSS-API Operational Paradigm . . . . . . . . . . . . . 8 65 4. Additional Controls . . . . . . . . . . . . . . . . . 9 66 4.1. Delegation . . . . . . . . . . . . . . . . . . . . . . 10 67 4.2. Mutual Authentication . . . . . . . . . . . . . . . . 11 68 4.3. Replay and Out-of-Sequence Detection . . . . . . . . . 11 69 4.4. Anonymous Authentication . . . . . . . . . . . . . . . 12 70 4.5. Confidentiality . . . . . . . . . . . . . . . . . . . 13 71 4.6. Inter-process Context Transfer . . . . . . . . . . . . 13 72 4.7. The Use of Incomplete Contexts . . . . . . . . . . . . 14 73 5. Calling Conventions . . . . . . . . . . . . . . . . . 14 74 5.1. Package Name . . . . . . . . . . . . . . . . . . . . . 15 75 5.2. Provider Framework . . . . . . . . . . . . . . . . . . 15 76 5.3. Integer Types . . . . . . . . . . . . . . . . . . . . 16 77 5.4. Opaque Data Types . . . . . . . . . . . . . . . . . . 16 78 5.5. Strings . . . . . . . . . . . . . . . . . . . . . . . 16 79 5.6. Object Identifiers . . . . . . . . . . . . . . . . . . 16 80 5.7. Object Identifier Sets . . . . . . . . . . . . . . . . 16 81 5.8. Credentials . . . . . . . . . . . . . . . . . . . . . 17 82 5.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . 19 83 5.10. Authentication Tokens . . . . . . . . . . . . . . . . 19 84 5.11. Interprocess Tokens . . . . . . . . . . . . . . . . . 19 85 5.12. Error Reporting . . . . . . . . . . . . . . . . . . . 20 86 5.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . . 20 87 5.12.2. Mechanism-Specific Status Codes . . . . . . . . . . . 23 88 5.12.3. Supplementary Status Codes . . . . . . . . . . . . . . 23 89 5.13. Names . . . . . . . . . . . . . . . . . . . . . . . . 23 90 5.14. Channel Bindings . . . . . . . . . . . . . . . . . . . 26 91 5.15. Stream Objects . . . . . . . . . . . . . . . . . . . . 27 92 5.16. Optional Parameters . . . . . . . . . . . . . . . . . 27 93 6. Introduction to GSS-API Classes and Interfaces . . . . 27 94 6.1. GSSManager class . . . . . . . . . . . . . . . . . . . 28 95 6.2. GSSName interface . . . . . . . . . . . . . . . . . . 29 96 6.3. GSSCredential interface . . . . . . . . . . . . . . . 29 97 6.4. GSSContext interface . . . . . . . . . . . . . . . . . 30 98 6.5. MessageProp class . . . . . . . . . . . . . . . . . . 31 99 6.6. GSSException class . . . . . . . . . . . . . . . . . . 31 100 6.7. Oid class . . . . . . . . . . . . . . . . . . . . . . 32 101 6.8. ChannelBinding class . . . . . . . . . . . . . . . . . 32 102 7. Detailed GSS-API Class Description . . . . . . . . . . 32 103 7.1. public abstract class GSSManager . . . . . . . . . . . 32 104 7.1.1. Example Code . . . . . . . . . . . . . . . . . . . . . 33 105 7.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 34 106 7.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . . 34 107 7.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 34 108 7.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 34 109 7.1.6. createName . . . . . . . . . . . . . . . . . . . . . . 35 110 7.1.7. createName . . . . . . . . . . . . . . . . . . . . . . 35 111 7.1.8. createName . . . . . . . . . . . . . . . . . . . . . . 36 112 7.1.9. createName . . . . . . . . . . . . . . . . . . . . . . 36 113 7.1.10. createCredential . . . . . . . . . . . . . . . . . . . 37 114 7.1.11. createCredential . . . . . . . . . . . . . . . . . . . 37 115 7.1.12. createCredential . . . . . . . . . . . . . . . . . . . 38 116 7.1.13. createContext . . . . . . . . . . . . . . . . . . . . 38 117 7.1.14. createContext . . . . . . . . . . . . . . . . . . . . 39 118 7.1.15. createContext . . . . . . . . . . . . . . . . . . . . 39 119 7.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . . 39 120 7.1.17. Example Code . . . . . . . . . . . . . . . . . . . . . 40 121 7.1.18. addProviderAtEnd . . . . . . . . . . . . . . . . . . . 41 122 7.1.19. Example Code . . . . . . . . . . . . . . . . . . . . . 42 123 7.2. public interface GSSName . . . . . . . . . . . . . . . 42 124 7.2.1. Example Code . . . . . . . . . . . . . . . . . . . . . 43 125 7.2.2. Static Constants . . . . . . . . . . . . . . . . . . . 43 126 7.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 44 127 7.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 45 128 7.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . . 45 129 7.2.6. export . . . . . . . . . . . . . . . . . . . . . . . . 45 130 7.2.7. toString . . . . . . . . . . . . . . . . . . . . . . . 45 131 7.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 46 132 7.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 46 133 7.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . . 46 134 7.3. public interface GSSCredential implements Cloneable . 46 135 7.3.1. Example Code . . . . . . . . . . . . . . . . . . . . . 47 136 7.3.2. Static Constants . . . . . . . . . . . . . . . . . . . 48 137 7.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 48 138 7.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 48 139 7.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 48 140 7.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . . 49 141 7.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . . 49 142 7.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . . 49 143 7.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . . 50 144 7.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . . 50 145 7.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . . 50 146 7.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 50 147 7.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . . 51 148 7.4. public interface GSSContext . . . . . . . . . . . . . 51 149 7.4.1. Example Code . . . . . . . . . . . . . . . . . . . . . 52 150 7.4.2. Static Constants . . . . . . . . . . . . . . . . . . . 54 151 7.4.3. initSecContext . . . . . . . . . . . . . . . . . . . . 54 152 7.4.4. Example Code . . . . . . . . . . . . . . . . . . . . . 55 153 7.4.5. initSecContext . . . . . . . . . . . . . . . . . . . . 55 154 7.4.6. Example Code . . . . . . . . . . . . . . . . . . . . . 56 155 7.4.7. acceptSecContext . . . . . . . . . . . . . . . . . . . 57 156 7.4.8. Example Code . . . . . . . . . . . . . . . . . . . . . 58 157 7.4.9. acceptSecContext . . . . . . . . . . . . . . . . . . . 58 158 7.4.10. Example Code . . . . . . . . . . . . . . . . . . . . . 59 159 7.4.11. isEstablished . . . . . . . . . . . . . . . . . . . . 60 160 7.4.12. dispose . . . . . . . . . . . . . . . . . . . . . . . 60 161 7.4.13. getWrapSizeLimit . . . . . . . . . . . . . . . . . . . 60 162 7.4.14. wrap . . . . . . . . . . . . . . . . . . . . . . . . . 61 163 7.4.15. wrap . . . . . . . . . . . . . . . . . . . . . . . . . 62 164 7.4.16. unwrap . . . . . . . . . . . . . . . . . . . . . . . . 63 165 7.4.17. unwrap . . . . . . . . . . . . . . . . . . . . . . . . 63 166 7.4.18. getMIC . . . . . . . . . . . . . . . . . . . . . . . . 64 167 7.4.19. getMIC . . . . . . . . . . . . . . . . . . . . . . . . 65 168 7.4.20. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 65 169 7.4.21. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 66 170 7.4.22. export . . . . . . . . . . . . . . . . . . . . . . . . 67 171 7.4.23. requestMutualAuth . . . . . . . . . . . . . . . . . . 68 172 7.4.24. requestReplayDet . . . . . . . . . . . . . . . . . . . 68 173 7.4.25. requestSequenceDet . . . . . . . . . . . . . . . . . . 68 174 7.4.26. requestCredDeleg . . . . . . . . . . . . . . . . . . . 68 175 7.4.27. requestAnonymity . . . . . . . . . . . . . . . . . . . 69 176 7.4.28. requestConf . . . . . . . . . . . . . . . . . . . . . 69 177 7.4.29. requestInteg . . . . . . . . . . . . . . . . . . . . . 69 178 7.4.30. requestLifetime . . . . . . . . . . . . . . . . . . . 69 179 7.4.31. setChannelBinding . . . . . . . . . . . . . . . . . . 70 180 7.4.32. getCredDelegState . . . . . . . . . . . . . . . . . . 70 181 7.4.33. getMutualAuthState . . . . . . . . . . . . . . . . . . 70 182 7.4.34. getReplayDetState . . . . . . . . . . . . . . . . . . 70 183 7.4.35. getSequenceDetState . . . . . . . . . . . . . . . . . 71 184 7.4.36. getAnonymityState . . . . . . . . . . . . . . . . . . 71 185 7.4.37. isTransferable . . . . . . . . . . . . . . . . . . . . 71 186 7.4.38. isProtReady . . . . . . . . . . . . . . . . . . . . . 71 187 7.4.39. getConfState . . . . . . . . . . . . . . . . . . . . . 71 188 7.4.40. getIntegState . . . . . . . . . . . . . . . . . . . . 72 189 7.4.41. getLifetime . . . . . . . . . . . . . . . . . . . . . 72 190 7.4.42. getSrcName . . . . . . . . . . . . . . . . . . . . . . 72 191 7.4.43. getTargName . . . . . . . . . . . . . . . . . . . . . 72 192 7.4.44. getMech . . . . . . . . . . . . . . . . . . . . . . . 72 193 7.4.45. getDelegCred . . . . . . . . . . . . . . . . . . . . . 72 194 7.4.46. isInitiator . . . . . . . . . . . . . . . . . . . . . 73 195 7.5. public class MessageProp . . . . . . . . . . . . . . . 73 196 7.5.1. Constructors . . . . . . . . . . . . . . . . . . . . . 73 197 7.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . . 74 198 7.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . . 74 199 7.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . . 74 200 7.5.5. getMinorString . . . . . . . . . . . . . . . . . . . . 74 201 7.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . . 74 202 7.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . . 74 203 7.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . . 75 204 7.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . . 75 205 7.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . . 75 206 7.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . . 75 207 7.5.12. setSupplementaryStates . . . . . . . . . . . . . . . . 75 208 7.6. public class ChannelBinding . . . . . . . . . . . . . 76 209 7.6.1. Constructors . . . . . . . . . . . . . . . . . . . . . 76 210 7.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 77 211 7.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . . 77 212 7.6.4. getApplicationData . . . . . . . . . . . . . . . . . . 77 213 7.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 77 214 7.7. public class Oid . . . . . . . . . . . . . . . . . . . 78 215 7.7.1. Constructors . . . . . . . . . . . . . . . . . . . . . 78 216 7.7.2. toString . . . . . . . . . . . . . . . . . . . . . . . 79 217 7.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 79 218 7.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . . 79 219 7.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 79 220 7.8. public class GSSException extends Exception . . . . . 79 221 7.8.1. Static Constants . . . . . . . . . . . . . . . . . . . 80 222 7.8.2. Constructors . . . . . . . . . . . . . . . . . . . . . 82 223 7.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . . 83 224 7.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . . 83 225 7.8.5. getMajorString . . . . . . . . . . . . . . . . . . . . 83 226 7.8.6. getMinorString . . . . . . . . . . . . . . . . . . . . 83 227 7.8.7. setMinor . . . . . . . . . . . . . . . . . . . . . . . 83 228 7.8.8. toString . . . . . . . . . . . . . . . . . . . . . . . 84 229 7.8.9. getMessage . . . . . . . . . . . . . . . . . . . . . . 84 230 8. Sample Applications . . . . . . . . . . . . . . . . . 84 231 8.1. Simple GSS Context Initiator . . . . . . . . . . . . . 84 232 8.2. Simple GSS Context Acceptor . . . . . . . . . . . . . 88 233 9. Security Considerations . . . . . . . . . . . . . . . 92 234 10. IANA Considerations . . . . . . . . . . . . . . . . . 92 235 11. Acknowledgments . . . . . . . . . . . . . . . . . . . 93 236 Appendix A. Changes since RFC 2853 . . . . . . . . . . . . . . . . 93 237 12. References . . . . . . . . . . . . . . . . . . . . . . 94 238 12.1. Normative References . . . . . . . . . . . . . . . . . 94 239 12.2. Informative References . . . . . . . . . . . . . . . . 94 240 Authors' Addresses . . . . . . . . . . . . . . . . . . 94 241 Intellectual Property and Copyright Statements . . . . 96 243 1. Conventions Used in This Document 245 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 246 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 247 document are to be interpreted as described in [RFC2119]. 249 2. Introduction 251 This document specifies Java language bindings for the Generic 252 Security Services Application Programming Interface Version 2 (GSS- 253 API). GSS-API Version 2 is described in a language independent 254 format in RFC 2743 [GSSAPIv2-UPDATE]. The GSS-API allows a caller 255 application to authenticate a principal identity, to delegate rights 256 to a peer, and to apply security services such as confidentiality and 257 integrity on a per-message basis. 259 This document and its predecessor RFC 2853 [RFC2853] leverage the 260 work done by the WG in the area of RFC 2743 [GSSAPIv2-UPDATE] and the 261 C-bindings RFC 2744 [GSSAPI-Cbind]. Whenever appropriate, text has 262 been used from the C-bindings RFC 2744 to explain generic concepts 263 and provide direction to the implementors. 265 The design goals of this API have been to satisfy all the 266 functionality defined in RFC 2743 [GSSAPIv2-UPDATE] and to provide 267 these services in an object oriented method. The specification also 268 aims to satisfy the needs of both types of Java application 269 developers, those who would like access to a "system-wide" GSS-API 270 implementation, as well as those who would want to provide their own 271 "custom" implementation. 273 A "system-wide" implementation is one that is available to all 274 applications in the form of a library package. It may be the 275 standard package in the Java runtime environment (JRE) being used or 276 it may be additionally installed and accessible to any application 277 via the CLASSPATH. 279 A "custom" implementation of the GSS-API, on the other hand, is one 280 that would, in most cases, be bundled with the application during 281 distribution. It is expected that such an implementation would be 282 meant to provide for some particular need of the application, such as 283 support for some specific mechanism. 285 The design of this API also aims to provide a flexible framework to 286 add and manage GSS-API mechanisms. GSS-API leverages the Java 287 Cryptography Architecture (JCA) provider model to support the 288 plugability of mechanisms. Mechanisms can be added on a "system- 289 wide" basis, where all users of the framework will have them 290 available. The specification also allows for the addition of 291 mechanisms per-instance of the GSS-API. 293 Lastly, this specification presents an API that will naturally fit 294 within the operation environment of the Java platform. Readers are 295 assumed to be familiar with both the GSS-API and the Java platform. 297 3. GSS-API Operational Paradigm 299 The Generic Security Service Application Programming Interface 300 Version 2 [GSSAPIv2-UPDATE] defines a generic security API to calling 301 applications. It allows a communicating application to authenticate 302 the user associated with another application, to delegate rights to 303 another application, and to apply security services such as 304 confidentiality and integrity on a per-message basis. 306 There are four stages to using GSS-API: 308 1) The application acquires a set of credentials with which it may 309 prove its identity to other processes. The application's credentials 310 vouch for its global identity, which may or may not be related to any 311 local username under which it may be running. 313 2) A pair of communicating applications establish a joint security 314 context using their credentials. The security context encapsulates 315 shared state information, which is required in order that per-message 316 security services may be provided. Examples of state information 317 that might be shared between applications as part of a security 318 context are cryptographic keys, and message sequence numbers. As 319 part of the establishment of a security context, the context 320 initiator is authenticated to the responder, and may require that the 321 responder is authenticated back to the initiator. The initiator may 322 optionally give the responder the right to initiate further security 323 contexts, acting as an agent or delegate of the initiator. This 324 transfer of rights is termed "delegation", and is achieved by 325 creating a set of credentials, similar to those used by the 326 initiating application, but which may be used by the responder. 328 A GSSContext object is used to establish and maintain the shared 329 information that makes up the security context. Certain GSSContext 330 methods will generate a token, which applications treat as 331 cryptographically protected, opaque data. The caller of such 332 GSSContext method is responsible for transferring the token to the 333 peer application, encapsulated if necessary in an application-to- 334 application protocol. On receipt of such a token, the peer 335 application should pass it to a corresponding GSSContext method which 336 will decode the token and extract the information, updating the 337 security context state information accordingly. 339 3) Per-message services are invoked on a GSSContext object to apply 340 either: 342 integrity and data origin authentication, or 344 confidentiality, integrity and data origin authentication 346 to application data, which are treated by GSS-API as arbitrary octet- 347 strings. An application transmitting a message that it wishes to 348 protect will call the appropriate GSSContext method (getMIC or wrap) 349 to apply protection, and send the resulting token to the receiving 350 application. The receiver will pass the received token (and, in the 351 case of data protected by getMIC, the accompanying message-data) to 352 the corresponding decoding method of the GSSContext interface 353 (verifyMIC or unwrap) to remove the protection and validate the data. 355 4) At the completion of a communications session (which may extend 356 across several transport connections), each application uses a 357 GSSContext method to invalidate the security context and release any 358 system or cryptographic resources held. Multiple contexts may also 359 be used (either successively or simultaneously) within a single 360 communications association, at the discretion of the applications. 362 4. Additional Controls 364 This section discusses the optional services that a context initiator 365 may request of the GSS-API before the context establishment. Each of 366 these services is requested by calling the appropriate mutator method 367 in the GSSContext object before the first call to init is performed. 368 Only the context initiator can request context flags. 370 The optional services defined are: 372 Delegation The (usually temporary) transfer of rights from 373 initiator to acceptor, enabling the acceptor to authenticate 374 itself as an agent of the initiator. 376 Mutual Authentication In addition to the initiator authenticating 377 its identity to the context acceptor, the context acceptor should 378 also authenticate itself to the initiator. 380 Replay Detection In addition to providing message integrity 381 services, GSSContext per-message operations of getMIC and wrap 382 should include message numbering information to enable verifyMIC 383 and unwrap to detect if a message has been duplicated. 385 Out-of-Sequence Detection In addition to providing message 386 integrity services, GSSContext per-message operations (getMIC and 387 wrap) should include message sequencing information to enable 388 verifyMIC and unwrap to detect if a message has been received out 389 of sequence. 391 Anonymous Authentication The establishment of the security context 392 should not reveal the initiator's identity to the context 393 acceptor. 395 Some mechanisms may not support all optional services, and some 396 mechanisms may only support some services in conjunction with others. 397 The GSSContext interface offers query methods to allow the 398 verification by the calling application of which services will be 399 available from the context when the establishment phase is complete. 400 In general, if the security mechanism is capable of providing a 401 requested service, it should do so even if additional services must 402 be enabled in order to provide the requested service. If the 403 mechanism is incapable of providing a requested service, it should 404 proceed without the service leaving the application to abort the 405 context establishment process if it considers the requested service 406 to be mandatory. 408 Some mechanisms may specify that support for some services is 409 optional, and that implementors of the mechanism need not provide it. 410 This is most commonly true of the confidentiality service, often 411 because of legal restrictions on the use of data-encryption, but may 412 apply to any of the services. Such mechanisms are required to send 413 at least one token from acceptor to initiator during context 414 establishment when the initiator indicates a desire to use such a 415 service, so that the initiating GSS-API can correctly indicate 416 whether the service is supported by the acceptor's GSS-API. 418 4.1. Delegation 420 The GSS-API allows delegation to be controlled by the initiating 421 application via the requestCredDeleg method before the first call to 422 init has been issued. Some mechanisms do not support delegation, and 423 for such mechanisms attempts by an application to enable delegation 424 are ignored. 426 The acceptor of a security context, for which the initiator enabled 427 delegation, can check if delegation was enabled by using the 428 getCredDelegState method of the GSSContext interface. In cases when 429 it is, the delegated credential object can be obtained by calling the 430 getDelegCred method. The obtained GSSCredential object may then be 431 used to initiate subsequent GSS-API security contexts as an agent or 432 delegate of the initiator. If the original initiator's identity is 433 "A" and the delegate's identity is "B", then, depending on the 434 underlying mechanism, the identity embodied by the delegated 435 credential may be either "A" or "B acting for A". 437 For many mechanisms that support delegation, a simple boolean does 438 not provide enough control. Examples of additional aspects of 439 delegation control that a mechanism might provide to an application 440 are duration of delegation, network addresses from which delegation 441 is valid, and constraints on the tasks that may be performed by a 442 delegate. Such controls are presently outside the scope of the GSS- 443 API. GSS-API implementations supporting mechanisms offering 444 additional controls should provide extension routines that allow 445 these controls to be exercised (perhaps by modifying the initiator's 446 GSS-API credential object prior to its use in establishing a 447 context). However, the simple delegation control provided by GSS-API 448 should always be able to over-ride other mechanism-specific 449 delegation controls. If the application instructs the GSSContext 450 object that delegation is not desired, then the implementation must 451 not permit delegation to occur. This is an exception to the general 452 rule that a mechanism may enable services even if they are not 453 requested - delegation may only be provided at the explicit request 454 of the application. 456 4.2. Mutual Authentication 458 Usually, a context acceptor will require that a context initiator 459 authenticate itself so that the acceptor may make an access-control 460 decision prior to performing a service for the initiator. In some 461 cases, the initiator may also request that the acceptor authenticate 462 itself. GSS-API allows the initiating application to request this 463 mutual authentication service by calling the requestMutualAuth method 464 of the GSSContext interface with a "true" parameter before making the 465 first call to init. The initiating application is informed as to 466 whether or not the context acceptor has authenticated itself. Note 467 that some mechanisms may not support mutual authentication, and other 468 mechanisms may always perform mutual authentication, whether or not 469 the initiating application requests it. In particular, mutual 470 authentication may be required by some mechanisms in order to support 471 replay or out-of-sequence message detection, and for such mechanisms 472 a request for either of these services will automatically enable 473 mutual authentication. 475 4.3. Replay and Out-of-Sequence Detection 477 The GSS-API may provide detection of mis-ordered messages once a 478 security context has been established. Protection may be applied to 479 messages by either application, by calling either getMIC or wrap 480 methods of the GSSContext interface, and verified by the peer 481 application by calling verifyMIC or unwrap for the peer's GSSContext 482 object. 484 The getMIC method calculates a cryptographic checksum of an 485 application message, and returns that checksum in a token. The 486 application should pass both the token and the message to the peer 487 application, which presents them to the verifyMIC method of the 488 peer's GSSContext object. 490 The wrap method calculates a cryptographic checksum of an application 491 message, and places both the checksum and the message inside a single 492 token. The application should pass the token to the peer 493 application, which presents it to the unwrap method of the peer's 494 GSSContext object to extract the message and verify the checksum. 496 Either pair of routines may be capable of detecting out-of-sequence 497 message delivery, or duplication of messages. Details of such mis- 498 ordered messages are indicated through supplementary query methods of 499 the MessageProp object that is filled in by each of these routines. 501 A mechanism need not maintain a list of all tokens that have been 502 processed in order to support these status codes. A typical 503 mechanism might retain information about only the most recent "N" 504 tokens processed, allowing it to distinguish duplicates and missing 505 tokens within the most recent "N" messages; the receipt of a token 506 older than the most recent "N" would result in the isOldToken method 507 of the instance of MessageProp to return "true". 509 4.4. Anonymous Authentication 511 In certain situations, an application may wish to initiate the 512 authentication process to authenticate a peer, without revealing its 513 own identity. As an example, consider an application providing 514 access to a database containing medical information, and offering 515 unrestricted access to the service. A client of such a service might 516 wish to authenticate the service (in order to establish trust in any 517 information retrieved from it), but might not wish the service to be 518 able to obtain the client's identity (perhaps due to privacy concerns 519 about the specific inquiries, or perhaps simply to avoid being placed 520 on mailing-lists). 522 In normal use of the GSS-API, the initiator's identity is made 523 available to the acceptor as a result of the context establishment 524 process. However, context initiators may request that their identity 525 not be revealed to the context acceptor. Many mechanisms do not 526 support anonymous authentication, and for such mechanisms the request 527 will not be honored. An authentication token will still be 528 generated, but the application is always informed if a requested 529 service is unavailable, and has the option to abort context 530 establishment if anonymity is valued above the other security 531 services that would require a context to be established. 533 In addition to informing the application that a context is 534 established anonymously (via the isAnonymous method of the GSSContext 535 class), the getSrcName method of the acceptor's GSSContext object 536 will, for such contexts, return a reserved internal-form name, 537 defined by the implementation. 539 The toString method for a GSSName object representing an anonymous 540 entity will return a printable name. The returned value will be 541 syntactically distinguishable from any valid principal name supported 542 by the implementation. The associated name-type object identifier 543 will be an oid representing the value of NT_ANONYMOUS. This name- 544 type oid will be defined as a public, static Oid object of the 545 GSSName class. The printable form of an anonymous name should be 546 chosen such that it implies anonymity, since this name may appear in, 547 for example, audit logs. For example, the string "" might 548 be a good choice, if no valid printable names supported by the 549 implementation can begin with "<" and end with ">". 551 When using the equal method of the GSSName interface, and one of the 552 operands is a GSSName instance representing an anonymous entity, the 553 method must return "false". 555 4.5. Confidentiality 557 If a GSSContext supports the confidentiality service, wrap method may 558 be used to encrypt application messages. Messages are selectively 559 encrypted, under the control of the setPrivacy method of the 560 MessageProp object used in the wrap method. 562 4.6. Inter-process Context Transfer 564 GSS-API V2 provides functionality which allows a security context to 565 be transferred between processes on a single machine. These are 566 implemented using the export method of GSSContext and a byte array 567 constructor of the same class. The most common use for such a 568 feature is a client-server design where the server is implemented as 569 a single process that accepts incoming security contexts, which then 570 launches child processes to deal with the data on these contexts. In 571 such a design, the child processes must have access to the security 572 context object created within the parent so that they can use per- 573 message protection services and delete the security context when the 574 communication session ends. 576 Since the security context data structure is expected to contain 577 sequencing information, it is impractical in general to share a 578 context between processes. Thus GSSContext interface provides an 579 export method that the process, which currently owns the context, can 580 call to declare that it has no intention to use the context 581 subsequently, and to create an inter-process token containing 582 information needed by the adopting process to successfully re-create 583 the context. After successful completion of export, the original 584 security context is made inaccessible to the calling process by GSS- 585 API and any further usage of this object will result in failures. 586 The originating process transfers the inter-process token to the 587 adopting process, which creates a new GSSContext object using the 588 byte array constructor. The properties of the context are equivalent 589 to that of the original context. 591 The inter-process token may contain sensitive data from the original 592 security context (including cryptographic keys). Applications using 593 inter-process tokens to transfer security contexts must take 594 appropriate steps to protect these tokens in transit. 596 Implementations are not required to support the inter-process 597 transfer of security contexts. Calling the isTransferable method of 598 the GSSContext interface will indicate if the context object is 599 transferable. 601 4.7. The Use of Incomplete Contexts 603 Some mechanisms may allow the per-message services to be used before 604 the context establishment process is complete. For example, a 605 mechanism may include sufficient information in its initial context- 606 level tokens for the context acceptor to immediately decode messages 607 protected with wrap or getMIC. For such a mechanism, the initiating 608 application need not wait until subsequent context-level tokens have 609 been sent and received before invoking the per-message protection 610 services. 612 An application can invoke the isProtReady method of the GSSContext 613 class to determine if the per-message services are available in 614 advance of complete context establishment. Applications wishing to 615 use per-message protection services on partially-established contexts 616 should query this method before attempting to invoke wrap or getMIC. 618 5. Calling Conventions 620 Java provides the implementors with not just a syntax for the 621 language, but also an operational environment. For example, memory 622 is automatically managed and does not require application 623 intervention. These language features have allowed for a simpler API 624 and have led to the elimination of certain GSS-API functions. 626 Moreover, the JCA defines a provider model which allows for 627 implementation independent access to security services. Using this 628 model, applications can seamlessly switch between different 629 implementations and dynamically add new services. The GSS-API 630 specification leverages these concepts by the usage of providers for 631 the mechanism implementations. 633 5.1. Package Name 635 The classes and interfaces defined in this document reside in the 636 package called "org.ietf.jgss". Applications that wish to make use 637 of this API should import this package name as shown in section 8. 639 5.2. Provider Framework 641 The Java security API's use a provider architecture that allows 642 applications to be implementation independent and security API 643 implementations to be modular and extensible. The 644 java.security.Provider class is an abstract class that a vendor 645 extends. This class maps various properties that represent different 646 security services that are available to the names of the actual 647 vendor classes that implement those services. When requesting a 648 service, an application simply specifies the desired provider and the 649 API delegates the request to service classes available from that 650 provider. 652 Using the Java security provider model insulates applications from 653 implementation details of the services they wish to use. 654 Applications can switch between providers easily and new providers 655 can be added as needed, even at runtime. 657 The GSS-API may use providers to find components for specific 658 underlying security mechanisms. For instance, a particular provider 659 might contain components that will allow the GSS-API to support the 660 Kerberos v5 mechanism [RFC4121] and another might contain components 661 to support the SPKM [RFC2025] mechanism. By delegating mechanism 662 specific functionality to the components obtained from providers, the 663 GSS-API can be extended to support an arbitrary list of mechanism. 665 How the GSS-API locates and queries these providers is beyond the 666 scope of this document and is being deferred to a Service Provider 667 Interface (SPI) specification. The availability of such a SPI 668 specification is not mandatory for the adoption of this API 669 specification nor is it mandatory to use providers in the 670 implementation of a GSS-API framework. However, by using the 671 provider framework together with an SPI specification one can create 672 an extensible and implementation independent GSS-API framework. 674 5.3. Integer Types 676 All numeric values are declared as "int" primitive Java type. The 677 Java specification guarantees that this will be a 32 bit two's 678 complement signed number. 680 Throughout this API, the "boolean" primitive Java type is used 681 wherever a boolean value is required or returned. 683 5.4. Opaque Data Types 685 Java byte arrays are used to represent opaque data types which are 686 consumed and produced by the GSS-API in the forms of tokens. Java 687 arrays contain a length field which enables the users to easily 688 determine their size. The language has automatic garbage collection 689 which alleviates the need by developers to release memory and 690 simplifies buffer ownership issues. 692 5.5. Strings 694 The String object will be used to represent all textual data. The 695 Java String object, transparently treats all characters as two-byte 696 Unicode characters which allows support for many locals. All 697 routines returning or accepting textual data will use the String 698 object. 700 5.6. Object Identifiers 702 An Oid object will be used to represent Universal Object Identifiers 703 (Oids). Oids are ISO-defined, hierarchically globally-interpretable 704 identifiers used within the GSS-API framework to identify security 705 mechanisms and name formats. The Oid object can be created from a 706 string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as 707 well as from its ASN.1 DER encoding. Methods are also provided to 708 test equality and provide the DER representation for the object. 710 An important feature of the Oid class is that its instances are 711 immutable - i.e. there are no methods defined that allow one to 712 change the contents of an Oid. This property allows one to treat 713 these objects as "statics" without the need to perform copies. 715 Certain routines allow the usage of a default oid. A "null" value 716 can be used in those cases. 718 5.7. Object Identifier Sets 719 The Java bindings represents object identifiers sets as arrays of Oid 720 objects. All Java arrays contain a length field which allows for 721 easy manipulation and reference. 723 In order to support the full functionality of RFC 2743 724 [GSSAPIv2-UPDATE], the Oid class includes a method which checks for 725 existence of an Oid object within a specified array. This is 726 equivalent in functionality to gss_test_oid_set_member. The use of 727 Java arrays and Java's automatic garbage collection has eliminated 728 the need for the following routines: gss_create_empty_oid_set, 729 gss_release_oid_set, and gss_add_oid_set_member. Java GSS-API 730 implementations will not contain them. Java's automatic garbage 731 collection and the immutable property of the Oid object eliminates 732 the memory management issues of the C counterpart. 734 When ever a default value for an Object Identifier Set is required, a 735 "null" value can be used. Please consult the detailed method 736 description for details. 738 5.8. Credentials 740 GSS-API credentials are represented by the GSSCredential interface. 741 The interface contains several constructs to allow for the creation 742 of most common credential objects for the initiator and the acceptor. 743 Comparisons are performed using the interface's "equals" method. The 744 following general description of GSS-API credentials is included from 745 the C-bindings specification: 747 GSS-API credentials can contain mechanism-specific principal 748 authentication data for multiple mechanisms. A GSS-API credential is 749 composed of a set of credential-elements, each of which is applicable 750 to a single mechanism. A credential may contain at most one 751 credential-element for each supported mechanism. A credential- 752 element identifies the data needed by a single mechanism to 753 authenticate a single principal, and conceptually contains two 754 credential-references that describe the actual mechanism-specific 755 authentication data, one to be used by GSS-API for initiating 756 contexts, and one to be used for accepting contexts. For mechanisms 757 that do not distinguish between acceptor and initiator credentials, 758 both references would point to the same underlying mechanism-specific 759 authentication data. 761 Credentials describe a set of mechanism-specific principals, and give 762 their holder the ability to act as any of those principals. All 763 principal identities asserted by a single GSS-API credential should 764 belong to the same entity, although enforcement of this property is 765 an implementation-specific matter. A single GSSCredential object 766 represents all the credential elements that have been acquired. 768 The creation's of an GSSContext object allows the value of "null" to 769 be specified as the GSSCredential input parameter. This will 770 indicate a desire by the application to act as a default principal. 771 While individual GSS-API implementations are free to determine such 772 default behavior as appropriate to the mechanism, the following 773 default behavior by these routines is recommended for portability: 775 For the initiator side of the context: 777 1) If there is only a single principal capable of initiating security 778 contexts for the chosen mechanism that the application is authorized 779 to act on behalf of, then that principal shall be used, otherwise 781 2) If the platform maintains a concept of a default network- identity 782 for the chosen mechanism, and if the application is authorized to act 783 on behalf of that identity for the purpose of initiating security 784 contexts, then the principal corresponding to that identity shall be 785 used, otherwise 787 3) If the platform maintains a concept of a default local identity, 788 and provides a means to map local identities into network-identities 789 for the chosen mechanism, and if the application is authorized to act 790 on behalf of the network- identity image of the default local 791 identity for the purpose of initiating security contexts using the 792 chosen mechanism, then the principal corresponding to that identity 793 shall be used, otherwise 795 4) A user-configurable default identity should be used. 797 and for the acceptor side of the context 799 1) If there is only a single authorized principal identity capable of 800 accepting security contexts for the chosen mechanism, then that 801 principal shall be used, otherwise 803 2) If the mechanism can determine the identity of the target 804 principal by examining the context-establishment token processed 805 during the accept method, and if the accepting application is 806 authorized to act as that principal for the purpose of accepting 807 security contexts using the chosen mechanism, then that principal 808 identity shall be used, otherwise 810 3) If the mechanism supports context acceptance by any principal, and 811 if mutual authentication was not requested, any principal that the 812 application is authorized to accept security contexts under using the 813 chosen mechanism may be used, otherwise 815 4) A user-configurable default identity shall be used. 817 The purpose of the above rules is to allow security contexts to be 818 established by both initiator and acceptor using the default behavior 819 whenever possible. Applications requesting default behavior are 820 likely to be more portable across mechanisms and implementations than 821 ones that instantiate an GSSCredential object representing a specific 822 identity. 824 5.9. Contexts 826 The GSSContext interface is used to represent one end of a GSS-API 827 security context, storing state information appropriate to that end 828 of the peer communication, including cryptographic state information. 829 The instantiation of the context object is done differently by the 830 initiator and the acceptor. After the context has been instantiated, 831 the initiator may choose to set various context options which will 832 determine the characteristics of the desired security context. When 833 all the application desired characteristics have been set, the 834 initiator will call the initSecContext method which will produce a 835 token for consumption by the peer's acceptSecContext method. It is 836 the responsibility of the application to deliver the authentication 837 token(s) between the peer applications for processing. Upon 838 completion of the context establishment phase, context attributes can 839 be retrieved, by both the initiator and acceptor, using the accessor 840 methods. These will reflect the actual attributes of the established 841 context. At this point the context can be used by the application to 842 apply cryptographic services to its data. 844 5.10. Authentication Tokens 846 A token is a caller-opaque type that GSS-API uses to maintain 847 synchronization between each end of the GSS-API security context. 848 The token is a cryptographically protected octet-string, generated by 849 the underlying mechanism at one end of a GSS-API security context for 850 use by the peer mechanism at the other end. Encapsulation (if 851 required) within the application protocol and transfer of the token 852 are the responsibility of the peer applications. 854 Java GSS-API uses byte arrays to represent authentication tokens. 855 Overloaded methods exist which allow the caller to supply input and 856 output streams which will be used for the reading and writing of the 857 token data. 859 5.11. Interprocess Tokens 861 Certain GSS-API routines are intended to transfer data between 862 processes in multi-process programs. These routines use a caller- 863 opaque octet-string, generated by the GSS-API in one process for use 864 by the GSS-API in another process. The calling application is 865 responsible for transferring such tokens between processes. Note 866 that, while GSS-API implementors are encouraged to avoid placing 867 sensitive information within interprocess tokens, or to 868 cryptographically protect them, many implementations will be unable 869 to avoid placing key material or other sensitive data within them. 870 It is the application's responsibility to ensure that interprocess 871 tokens are protected in transit, and transferred only to processes 872 that are trustworthy. An interprocess token is represented using a 873 byte array emitted from the export method of the GSSContext 874 interface. The receiver of the interprocess token would initialize 875 an GSSContext object with this token to create a new context. Once a 876 context has been exported, the GSSContext object is invalidated and 877 is no longer available. 879 5.12. Error Reporting 881 RFC 2743 [GSSAPIv2-UPDATE] defined the usage of major and minor 882 status values for signaling of GSS-API errors. The major code, also 883 called GSS status code, is used to signal errors at the GSS-API level 884 independent of the underlying mechanism(s). The minor status value 885 or Mechanism status code, is a mechanism defined error value 886 indicating a mechanism specific error code. 888 Java GSS-API uses exceptions implemented by the GSSException class to 889 signal both minor and major error values. Both mechanism specific 890 errors and GSS-API level errors are signaled through instances of 891 this class. The usage of exceptions replaces the need for major and 892 minor codes to be used within the API calls. GSSException class also 893 contains methods to obtain textual representations for both the major 894 and minor values, which is equivalent to the functionality of 895 gss_display_status. 897 5.12.1. GSS Status Codes 899 GSS status codes indicate errors that are independent of the 900 underlying mechanism(s) used to provide the security service. The 901 errors that can be indicated via a GSS status code are generic API 902 routine errors (errors that are defined in the GSS-API 903 specification). These bindings take advantage of the Java exceptions 904 mechanism, thus eliminating the need for calling errors. 906 A GSS status code indicates a single fatal generic API error from the 907 routine that has thrown the GSSException. Using exceptions announces 908 that a fatal error has occurred during the execution of the method. 909 The GSS-API operational model also allows for the signaling of 910 supplementary status information from the per-message calls. These 911 need to be handled as return values since using exceptions is not 912 appropriate for informatory or warning-like information. The methods 913 that are capable of producing supplementary information are the two 914 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 915 These methods fill the supplementary status codes in the MessageProp 916 object that was passed in. 918 A GSSException object, along with providing the functionality for 919 setting of the various error codes and translating them into textual 920 representation, also contains the definitions of all the numeric 921 error values. The following table lists the definitions of error 922 codes: 924 Table: GSS Status Codes 926 Name Value Meaning 928 BAD_BINDINGS 1 Incorrect channel bindings were 929 supplied. 931 BAD_MECH 2 An unsupported mechanism 932 was requested. 934 BAD_NAME 3 An invalid name was supplied. 936 BAD_NAMETYPE 4 A supplied name was of an 937 unsupported type. 939 BAD_STATUS 5 An invalid status code was 940 supplied. 942 BAD_MIC 6 A token had an invalid MIC. 944 CONTEXT_EXPIRED 7 The context has expired. 946 CREDENTIALS_EXPIRED 8 The referenced credentials 947 have expired. 949 DEFECTIVE_CREDENTIAL 9 A supplied credential was 950 invalid. 952 DEFECTIVE_TOKEN 10 A supplied token was invalid. 954 FAILURE 11 Miscellaneous failure, 955 unspecified at the GSS-API 956 level. 958 NO_CONTEXT 12 Invalid context has been 959 supplied. 961 NO_CRED 13 No credentials were supplied, or 962 the credentials were unavailable 963 or inaccessible. 965 BAD_QOP 14 The quality-of-protection 966 requested could not be provided. 968 UNAUTHORIZED 15 The operation is forbidden by 969 the local security policy. 971 UNAVAILABLE 16 The operation or option is 972 unavailable. 974 DUPLICATE_ELEMENT 17 The requested credential 975 element already exists. 977 NAME_NOT_MN 18 The provided name was not a 978 mechanism name. 980 The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN, 981 UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException 982 only if detected during context establishment, in which case it 983 is a fatal error. (During per-message calls, these values are 984 indicated as supplementary information contained in the 985 MessageProp object.) They are: 987 DUPLICATE_TOKEN 19 The token was a duplicate of an 988 earlier version. 990 OLD_TOKEN 20 The token's validity period has 991 expired. 993 UNSEQ_TOKEN 21 A later token has already been 994 processed. 996 GAP_TOKEN 22 The expected token was not 997 received. 999 The GSS major status code of FAILURE is used to indicate that the 1000 underlying mechanism detected an error for which no specific GSS 1001 status code is defined. The mechanism-specific status code can 1002 provide more details about the error. 1004 The different major status codes that can be contained in the 1005 GSSException object thrown by the methods in this specification are 1006 the same as the major status codes returned by the corresponding 1007 calls in RFC 2743 [GSSAPIv2-UPDATE]. 1009 5.12.2. Mechanism-Specific Status Codes 1011 Mechanism-specific status codes are communicated in two ways, they 1012 are part of any GSSException thrown from the mechanism specific layer 1013 to signal a fatal error, or they are part of the MessageProp object 1014 that the per-message calls use to signal non-fatal errors. 1016 A default value of 0 in either the GSSException object or the 1017 MessageProp object will be used to represent the absence of any 1018 mechanism specific status code. 1020 5.12.3. Supplementary Status Codes 1022 Supplementary status codes are confined to the per-message methods of 1023 the GSSContext interface. Because of the informative nature of these 1024 errors it is not appropriate to use exceptions to signal them. 1025 Instead, the per-message operations of the GSSContext interface 1026 return these values in a MessageProp object. 1028 The MessageProp class defines query methods which return boolean 1029 values indicating the following supplementary states: 1031 Table: Supplementary Status Methods 1033 Method Name Meaning when "true" is returned 1035 isDuplicateToken The token was a duplicate of an 1036 earlier token. 1038 isOldToken The token's validity period has 1039 expired. 1041 isUnseqToken A later token has already been 1042 processed. 1044 isGapToken An expected per-message token was 1045 not received. 1047 "true" return value for any of the above methods indicates that the 1048 token exhibited the specified property. The application must 1049 determine the appropriate course of action for these supplementary 1050 values. They are not treated as errors by the GSS-API. 1052 5.13. Names 1054 A name is used to identify a person or entity. GSS-API authenticates 1055 the relationship between a name and the entity claiming the name. 1057 Since different authentication mechanisms may employ different 1058 namespaces for identifying their principals, GSS-API's naming support 1059 is necessarily complex in multi-mechanism environments (or even in 1060 some single-mechanism environments where the underlying mechanism 1061 supports multiple namespaces). 1063 Two distinct conceptual representations are defined for names: 1065 1) A GSS-API form represented by implementations of the GSSName 1066 interface: A single GSSName object may contain multiple names from 1067 different namespaces, but all names should refer to the same entity. 1068 An example of such an internal name would be the name returned from a 1069 call to the getName method of the GSSCredential interface, when 1070 applied to a credential containing credential elements for multiple 1071 authentication mechanisms employing different namespaces. This 1072 GSSName object will contain a distinct name for the entity for each 1073 authentication mechanism. 1075 For GSS-API implementations supporting multiple namespaces, GSSName 1076 implementations must contain sufficient information to determine the 1077 namespace to which each primitive name belongs. 1079 2) Mechanism-specific contiguous byte array and string forms: 1080 Different GSSName initialization methods are provided to handle both 1081 byte array and string formats and to accommodate various calling 1082 applications and name types. These formats are capable of containing 1083 only a single name (from a single namespace). Contiguous string 1084 names are always accompanied by an object identifier specifying the 1085 namespace to which the name belongs, and their format is dependent on 1086 the authentication mechanism that employs that name. The string name 1087 forms are assumed to be printable, and may therefore be used by GSS- 1088 API applications for communication with their users. The byte array 1089 name formats are assumed to be in non-printable formats (e.g. the 1090 byte array returned from the export method of the GSSName interface). 1092 A GSSName object can be converted to a contiguous representation by 1093 using the toString method. This will guarantee that the name will be 1094 converted to a printable format. Different initialization methods in 1095 the GSSName interface are defined allowing support for multiple 1096 syntaxes for each supported namespace, and allowing users the freedom 1097 to choose a preferred name representation. The toString method 1098 should use an implementation-chosen printable syntax for each 1099 supported name-type. To obtain the printable name type, 1100 getStringNameType method can be used. 1102 There is no guarantee that calling the toString method on the GSSName 1103 interface will produce the same string form as the original imported 1104 string name. Furthermore, it is possible that the name was not even 1105 constructed from a string representation. The same applies to name- 1106 space identifiers which may not necessarily survive unchanged after a 1107 journey through the internal name-form. An example of this might be 1108 a mechanism that authenticates X.500 names, but provides an 1109 algorithmic mapping of Internet DNS names into X.500. That 1110 mechanism's implementation of GSSName might, when presented with a 1111 DNS name, generate an internal name that contained both the original 1112 DNS name and the equivalent X.500 name. Alternatively, it might only 1113 store the X.500 name. In the latter case, the toString method of 1114 GSSName would most likely generate a printable X.500 name, rather 1115 than the original DNS name. 1117 The context acceptor can obtain a GSSName object representing the 1118 entity performing the context initiation (through the usage of 1119 getSrcName method). Since this name has been authenticated by a 1120 single mechanism, it contains only a single name (even if the 1121 internal name presented by the context initiator to the GSSContext 1122 object had multiple components). Such names are termed internal 1123 mechanism names, or "MN"s and the names emitted by GSSContext 1124 interface in the getSrcName and getTargName are always of this type. 1125 Since some applications may require MNs without wanting to incur the 1126 overhead of an authentication operation, creation methods are 1127 provided that take not only the name buffer and name type, but also 1128 the mechanism oid for which this name should be created. When 1129 dealing with an existing GSSName object, the canonicalize method may 1130 be invoked to convert a general internal name into an MN. 1132 GSSName objects can be compared using their equal method, which 1133 returns "true" if the two names being compared refer to the same 1134 entity. This is the preferred way to perform name comparisons 1135 instead of using the printable names that a given GSS-API 1136 implementation may support. Since GSS-API assumes that all primitive 1137 names contained within a given internal name refer to the same 1138 entity, equal can return "true" if the two names have at least one 1139 primitive name in common. If the implementation embodies knowledge 1140 of equivalence relationships between names taken from different 1141 namespaces, this knowledge may also allow successful comparisons of 1142 internal names containing no overlapping primitive elements. 1144 When used in large access control lists, the overhead of creating an 1145 GSSName object on each name and invoking the equal method on each 1146 name from the ACL may be prohibitive. As an alternative way of 1147 supporting this case, GSS-API defines a special form of the 1148 contiguous byte array name which may be compared directly (byte by 1149 byte). Contiguous names suitable for comparison are generated by the 1150 export method. Exported names may be re-imported by using the byte 1151 array constructor and specifying the NT_EXPORT_NAME as the name type 1152 object identifier. The resulting GSSName name will also be a MN. 1154 The GSSName interface defines public static Oid objects representing 1155 the standard name types. Structurally, an exported name object 1156 consists of a header containing an OID identifying the mechanism that 1157 authenticated the name, and a trailer containing the name itself, 1158 where the syntax of the trailer is defined by the individual 1159 mechanism specification. Detailed description of the format is 1160 specified in the language-independent GSS-API specification 1161 [GSSAPIv2-UPDATE]. 1163 Note that the results obtained by using the equals method will in 1164 general be different from those obtained by invoking canonicalize and 1165 export, and then comparing the byte array output. The first series 1166 of operation determines whether two (unauthenticated) names identify 1167 the same principal; the second whether a particular mechanism would 1168 authenticate them as the same principal. These two operations will 1169 in general give the same results only for MNs. 1171 It is important to note that the above are guidelines as how GSSName 1172 implementations should behave, and are not intended to be specific 1173 requirements of how names objects must be implemented. The mechanism 1174 designers are free to decide on the details of their implementations 1175 of the GSSName interface as long as the behavior satisfies the above 1176 guidelines. 1178 5.14. Channel Bindings 1180 GSS-API supports the use of user-specified tags to identify a given 1181 context to the peer application. These tags are intended to be used 1182 to identify the particular communications channel that carries the 1183 context. Channel bindings are communicated to the GSS-API using the 1184 ChannelBinding object. The application may use byte arrays to 1185 specify the application data to be used in the channel binding as 1186 well as using instances of the InetAddress. The InetAddress for the 1187 initiator and/or acceptor can be used within an instance of a 1188 ChannelBinding. ChannelBinding can be set for the GSSContext object 1189 using the setChannelBinding method before the first call to init or 1190 accept has been performed. Unless the setChannelBinding method has 1191 been used to set the ChannelBinding for a GSSContext object, "null" 1192 ChannelBinding will be assumed. InetAddress is currently the only 1193 address type defined within the Java platform and as such, it is the 1194 only one supported within the ChannelBinding class. Applications 1195 that use other types of addresses can include them as part of the 1196 application specific data. 1198 Conceptually, the GSS-API concatenates the initiator and acceptor 1199 address information, and the application supplied byte array to form 1200 an octet string. The mechanism calculates a MIC over this octet 1201 string and binds the MIC to the context establishment token emitted 1202 by init method of the GSSContext interface. The same bindings are 1203 set by the context acceptor for its GSSContext object and during 1204 processing of the accept method a MIC is calculated in the same way. 1205 The calculated MIC is compared with that found in the token, and if 1206 the MICs differ, accept will throw a GSSException with the major code 1207 set to BAD_BINDINGS, and the context will not be established. Some 1208 mechanisms may include the actual channel binding data in the token 1209 (rather than just a MIC); applications should therefore not use 1210 confidential data as channel-binding components. 1212 Individual mechanisms may impose additional constraints on addresses 1213 that may appear in channel bindings. For example, a mechanism may 1214 verify that the initiator address field of the channel binding 1215 contains the correct network address of the host system. Portable 1216 applications should therefore ensure that they either provide correct 1217 information for the address fields, or omit setting of the addressing 1218 information. 1220 5.15. Stream Objects 1222 The context object provides overloaded methods which use input and 1223 output streams as the means to convey authentication and per-message 1224 GSS-API tokens. It is important to note that the streams are 1225 expected to contain the usual GSS-API tokens which would otherwise be 1226 handled through the usage of byte arrays. The tokens are expected to 1227 have a definite start and an end. The callers are responsible for 1228 ensuring that the supplied streams will not block, or expect to block 1229 until a full token is processed by the GSS-API method. Only a single 1230 GSS-API token will be processed per invocation of the stream based 1231 method. 1233 The usage of streams allows the callers to have control and 1234 management of the supplied buffers. Because streams are non- 1235 primitive objects, the callers can make the streams as complicated or 1236 as simple as desired simply by using the streams defined in the 1237 java.io package or creating their own through the use of inheritance. 1238 This will allow for the application's greatest flexibility. 1240 5.16. Optional Parameters 1242 Whenever the application wishes to omit an optional parameter the 1243 "null" value shall be used. The detailed method descriptions 1244 indicate which parameters are optional. Methods overloading has also 1245 been used as a technique to indicate default parameters. 1247 6. Introduction to GSS-API Classes and Interfaces 1248 This section presents a brief description of the classes and 1249 interfaces that constitute the GSS-API. The implementations of these 1250 are obtained from the CLASSPATH defined by the application. If Java 1251 GSS becomes part of the standard Java API's then these classes will 1252 be available by default on all systems as part of the JRE's system 1253 classes. 1255 This section also shows the corresponding RFC 2743 [GSSAPIv2-UPDATE] 1256 functionality implemented by each of the classes. Detailed 1257 description of these classes and their methods is presented in 1258 section 7. 1260 6.1. GSSManager class 1262 This abstract class serves as a factory to instantiate 1263 implementations of the GSS-API interfaces and also provides methods 1264 to make queries about underlying security mechanisms. 1266 A default implementation can be obtained using the static method 1267 getInstance(). Applications that desire to provide their own 1268 implementation of the GSSManager class can simply extend the abstract 1269 class themselves. 1271 This class contains equivalents of the following RFC 2743 1272 [GSSAPIv2-UPDATE] routines: 1274 gss_import_name Create an internal name from 7.1.6- 1275 the supplied information. 7.1.9 1277 gss_acquire_cred Acquire credential 7.1.10- 1278 for use. 7.1.12 1280 gss_import_sec_context Create a previously exported 7.1.15 1281 context. 1283 gss_indicate_mechs List the mechanisms 7.1.3 1284 supported by this GSS-API 1285 implementation. 1287 gss_inquire_mechs_for_name List the mechanisms 7.1.5 1288 supporting the 1289 specified name type. 1291 gss_inquire_names_for_mech List the name types 7.1.4 1292 supported by the 1293 specified mechanism. 1295 6.2. GSSName interface 1297 GSS-API names are represented in the Java bindings through the 1298 GSSName interface. Different name formats and their definitions are 1299 identified with universal Object Identifiers (oids). The format of 1300 the names can be derived based on the unique oid of each name type. 1301 The following GSS-API routines are provided by the GSSName interface: 1303 RFC 2743 Routine Function Section(s) 1305 gss_display_name Covert internal name 7.2.7 1306 representation to text format. 1308 gss_compare_name Compare two internal names. 7.2.3, 1309 7.2.4 1311 gss_release_name Release resources associated N/A 1312 with the internal name. 1314 gss_canonicalize_name Convert an internal name to a 7.2.5 1315 mechanism name. 1317 gss_export_name Convert a mechanism name to 7.2.6 1318 export format. 1320 gss_duplicate_name Create a copy of the internal N/A 1321 name. 1323 The gss_release_name call is not provided as Java does its own 1324 garbage collection. The gss_duplicate_name call is also redundant; 1325 the GSSName interface has no mutator methods that can change the 1326 state of the object so it is safe for sharing across threads. 1328 6.3. GSSCredential interface 1330 The GSSCredential interface is responsible for the encapsulation of 1331 GSS-API credentials. Credentials identify a single entity and 1332 provide the necessary cryptographic information to enable the 1333 creation of a context on behalf of that entity. A single credential 1334 may contain multiple mechanism specific credentials, each referred to 1335 as a credential element. The GSSCredential interface provides the 1336 functionality of the following GSS-API routines: 1338 RFC 2743 Routine Function Section(s) 1340 gss_add_cred Constructs credentials 7.3.12 1341 incrementally. 1343 gss_inquire_cred Obtain information about 7.3.4- 1344 credential. 7.3.11 1346 gss_inquire_cred_by_mech Obtain per-mechanism 7.3.5- 1347 information about 7.3.10 1348 a credential. 1350 gss_release_cred Disposes of credentials 7.3.3 1351 after use. 1353 6.4. GSSContext interface 1355 This interface encapsulates the functionality of context-level calls 1356 required for security context establishment and management between 1357 peers as well as the per-message services offered to applications. A 1358 context is established between a pair of peers and allows the usage 1359 of security services on a per-message basis on application data. It 1360 is created over a single security mechanism. The GSSContext 1361 interface provides the functionality of the following GSS-API 1362 routines: 1364 RFC 2743 Routine Function Section(s) 1366 gss_init_sec_context Initiate the creation of a 7.4.3- 1367 security context with a peer. 7.4.6 1369 gss_accept_sec_context Accept a security context 7.4.7- 1370 initiated by a peer. 7.4.10 1372 gss_delete_sec_context Destroy a security context. 7.4.12 1374 gss_context_time Obtain remaining context 7.4.41 1375 time. 1377 gss_inquire_context Obtain context 7.4.32- 1378 characteristics. 7.3.46 1380 gss_wrap_size_limit Determine token-size limit 7.4.13 1381 for gss_wrap. 1383 gss_export_sec_context Transfer security context 7.4.22 1384 to another process. 1386 gss_get_mic Calculate a cryptographic 7.4.18, 1387 Message Integrity Code (MIC) 7.4.19 1388 for a message. 1390 gss_verify_mic Verify integrity on a received 7.4.20, 1391 message. 7.4.21 1393 gss_wrap Attach a MIC to a message and 7.4.14, 1394 optionally encrypt the message 7.4.15 1395 content. 1397 gss_unwrap Obtain a previously wrapped 7.4.16, 1398 application message verifying 7.4.17 1399 its integrity and optionally 1400 decrypting it. 1402 The functionality offered by the gss_process_context_token routine 1403 has not been included in the Java bindings specification. The 1404 corresponding functionality of gss_delete_sec_context has also been 1405 modified to not return any peer tokens. This has been proposed in 1406 accordance to the recommendations stated in RFC 2743 1407 [GSSAPIv2-UPDATE]. GSSContext does offer the functionality of 1408 destroying the locally-stored context information. 1410 6.5. MessageProp class 1412 This helper class is used in the per-message operations on the 1413 context. An instance of this class is created by the application and 1414 then passed into the per-message calls. In some cases, the 1415 application conveys information to the GSS-API implementation through 1416 this object and in other cases the GSS-API returns information to the 1417 application by setting it in this object. See the description of the 1418 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1419 GSSContext interfaces for details. 1421 6.6. GSSException class 1423 Exceptions are used in the Java bindings to signal fatal errors to 1424 the calling applications. This replaces the major and minor codes 1425 used in the C-bindings specification as a method of signaling 1426 failures. The GSSException class handles both minor and major codes, 1427 as well as their translation into textual representation. All GSS- 1428 API methods are declared as throwing this exception. 1430 RFC 2743 Routine Function Section 1432 gss_display_status Retrieve textual 7.8.5, 7.8.6, 1433 representation of error 7.8.8, 7.8.9 1434 codes. 1436 6.7. Oid class 1438 This utility class is used to represent Universal Object Identifiers 1439 and their associated operations. GSS-API uses object identifiers to 1440 distinguish between security mechanisms and name types. This class, 1441 aside from being used whenever an object identifier is needed, 1442 implements the following GSS-API functionality: 1444 RFC 2743 Routine Function Section 1446 gss_test_oid_set_member Determine if the specified oid 7.7.5 1447 is part of a set of oids. 1449 6.8. ChannelBinding class 1451 An instance of this class is used to specify channel binding 1452 information to the GSSContext object before the start of a security 1453 context establishment. The application may use a byte array to 1454 specify application data to be used in the channel binding as well as 1455 use instances of the InetAddress. InetAddress is currently the only 1456 address type defined within the Java platform and as such, it is the 1457 only one supported within the ChannelBinding class. Applications 1458 that use other types of addresses can include them as part of the 1459 application data. 1461 7. Detailed GSS-API Class Description 1463 This section lists a detailed description of all the public methods 1464 that each of the GSS-API classes and interfaces must provide. 1466 7.1. public abstract class GSSManager 1468 The GSSManager class is an abstract class that serves as a factory 1469 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1470 also provides methods for applications to determine what mechanisms 1471 are available from the GSS implementation and what nametypes these 1472 mechanisms support. An instance of the default GSSManager subclass 1473 may be obtained through the static method getInstance(), but 1474 applications are free to instantiate other subclasses of GSSManager. 1476 All but one method in this class are declared abstract. This means 1477 that subclasses have to provide the complete implementation for those 1478 methods. The only exception to this is the static method 1479 getInstance() which will have platform specific code to return an 1480 instance of the default subclass. 1482 Platform providers of GSS are required not to add any constructors to 1483 this class, private, public, or protected. This will ensure that all 1484 subclasses invoke only the default constructor provided to the base 1485 class by the compiler. 1487 A subclass extending the GSSManager abstract class may be implemented 1488 as a modular provider based layer that utilizes some well known 1489 service provider specification. The GSSManager API provides the 1490 application with methods to set provider preferences on such an 1491 implementation. These methods also allow the implementation to throw 1492 a well-defined exception in case provider based configuration is not 1493 supported. Applications that expect to be portable should be aware 1494 of this and recover cleanly by catching the exception. 1496 It is envisioned that there will be three most common ways in which 1497 providers will be used: 1499 1) The application does not care about what provider is used (the 1500 default case). 1502 2) The application wants a particular provider to be used 1503 preferentially, either for a particular mechanism or all the time, 1504 irrespective of mechanism. 1506 3) The application wants to use the locally configured providers as 1507 far as possible but if support is missing for one or more mechanisms 1508 then it wants to fall back on its own provider. 1510 The GSSManager class has two methods that enable these modes of 1511 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1512 have the effect of creating an ordered list of pairs 1513 where each pair indicates a preference of provider for a given oid. 1515 The use of these methods does not require any knowledge of whatever 1516 service provider specification the GSSManager subclass follows. It 1517 is hoped that these methods will serve the needs of most 1518 applications. Additional methods may be added to an extended 1519 GSSManager that could be part of a service provider specification 1520 that is standardized later. 1522 7.1.1. Example Code 1524 GSSManager mgr = GSSManager.getInstance(); 1526 // What mechs are available to us? 1527 Oid[] supportedMechs = mgr.getMechs(); 1529 // Set a preference for the provider to be used when support 1530 // is needed for the mechanisms: 1531 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1533 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1534 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1536 Provider p = (Provider) (new com.foo.security.Provider()); 1538 mgr.addProviderAtFront(p, krb); 1539 mgr.addProviderAtFront(p, spkm1); 1541 // What name types does this spkm implementation support? 1542 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1544 7.1.2. getInstance 1546 public static GSSManager getInstance() 1548 Returns the default GSSManager implementation. 1550 7.1.3. getMechs 1552 public abstract Oid[] getMechs() 1554 Returns an array of Oid objects indicating the mechanisms available 1555 to GSS-API callers. A "null" value is returned when no mechanism are 1556 available (an example of this would be when mechanism are dynamically 1557 configured, and currently no mechanisms are installed). 1559 7.1.4. getNamesForMech 1561 public abstract Oid[] getNamesForMech(Oid mech) 1562 throws GSSException 1564 Returns name type Oid's supported by the specified mechanism. 1566 Parameters: 1568 mech The Oid object for the mechanism to query. 1570 7.1.5. getMechsForName 1572 public abstract Oid[] getMechsForName(Oid nameType) 1574 Returns an array of Oid objects corresponding to the mechanisms that 1575 support the specific name type. "null" is returned when no mechanisms 1576 are found to support the specified name type. 1578 Parameters: 1580 nameType The Oid object for the name type. 1582 7.1.6. createName 1584 public abstract GSSName createName(String nameStr, Oid nameType) 1585 throws GSSException 1587 Factory method to convert a contiguous string name from the specified 1588 namespace to a GSSName object. In general, the GSSName object 1589 created will not be an MN; two examples that are exceptions to this 1590 are when the namespace type parameter indicates NT_EXPORT_NAME or 1591 when the GSS-API implementation is not multi-mechanism. 1593 Parameters: 1595 nameStr The string representing a printable form of the name to 1596 create. 1598 nameType The Oid specifying the namespace of the printable name 1599 supplied. Note that nameType serves to describe and qualify the 1600 interpretation of the input nameStr, it does not necessarily imply 1601 a type for the output GSSName implementation. "null" value can be 1602 used to specify that a mechanism specific default printable syntax 1603 should be assumed by each mechanism that examines nameStr. 1605 7.1.7. createName 1607 public abstract GSSName createName(byte[] name, Oid nameType) 1608 throws GSSException 1610 Factory method to convert a contiguous byte array containing a name 1611 from the specified namespace to a GSSName object. In general, the 1612 GSSName object created will not be an MN; two examples that are 1613 exceptions to this are when the namespace type parameter indicates 1614 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1615 mechanism. 1617 Parameters: 1619 name The byte array containing the name to create. 1621 nameType The Oid specifying the namespace of the name supplied in 1622 the byte array. Note that nameType serves to describe and qualify 1623 the interpretation of the input name byte array, it does not 1624 necessarily imply a type for the output GSSName implementation. 1625 "null" value can be used to specify that a mechanism specific 1626 default syntax should be assumed by each mechanism that examines 1627 the byte array. 1629 7.1.8. createName 1631 public abstract GSSName createName(String nameStr, Oid nameType, 1632 Oid mech) throws GSSException 1634 Factory method to convert a contiguous string name from the specified 1635 namespace to an GSSName object that is a mechanism name (MN). In 1636 other words, this method is a utility that does the equivalent of two 1637 steps: the createName described in 7.1.6 and then also the 1638 GSSName.canonicalize() described in 7.2.5. 1640 Parameters: 1642 nameStr The string representing a printable form of the name to 1643 create. 1645 nameType The Oid specifying the namespace of the printable name 1646 supplied. Note that nameType serves to describe and qualify the 1647 interpretation of the input nameStr, it does not necessarily imply 1648 a type for the output GSSName implementation. "null" value can be 1649 used to specify that a mechanism specific default printable syntax 1650 should be assumed when the mechanism examines nameStr. 1652 mech Oid specifying the mechanism for which this name should be 1653 created. 1655 7.1.9. createName 1657 public abstract GSSName createName(byte[] name, Oid nameType, 1658 Oid mech) throws GSSException 1660 Factory method to convert a contiguous byte array containing a name 1661 from the specified namespace to a GSSName object that is an MN. In 1662 other words, this method is a utility that does the equivalent of two 1663 steps: the createName described in 7.1.7 and then also the 1664 GSSName.canonicalize() described in 7.2.5. 1666 Parameters: 1668 name The byte array representing the name to create. 1670 nameType The Oid specifying the namespace of the name supplied in 1671 the byte array. Note that nameType serves to describe and qualify 1672 the interpretation of the input name byte array, it does not 1673 necessarily imply a type for the output GSSName implementation. 1674 "null" value can be used to specify that a mechanism specific 1675 default syntax should be assumed by each mechanism that examines 1676 the byte array. 1678 mech Oid specifying the mechanism for which this name should be 1679 created. 1681 7.1.10. createCredential 1683 public abstract GSSCredential createCredential(int usage) 1684 throws GSSException 1686 Factory method for acquiring default credentials. This will cause 1687 the GSS-API to use system specific defaults for the set of 1688 mechanisms, name, and a DEFAULT lifetime. 1690 Parameters: 1692 usage The intended usage for this credential object.The value of 1693 this parameter must be one of: 1694 GSSCredential.INITIATE_AND_ACCEPT(0), 1695 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1697 7.1.11. createCredential 1699 public abstract GSSCredential createCredential(GSSName aName, 1700 int lifetime, Oid mech, int usage) 1701 throws GSSException 1703 Factory method for acquiring a single mechanism credential. 1705 Parameters: 1707 aName Name of the principal for whom this credential is to be 1708 acquired. Use "null" to specify the default principal. 1710 lifetime The number of seconds that credentials should remain 1711 valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the 1712 credentials have the maximum permitted lifetime. Use 1713 GSSCredential.DEFAULT_LIFETIME to request default credential 1714 lifetime. 1716 mech The oid of the desired mechanism. Use "(Oid) null" to 1717 request the default mechanism(s). 1719 usage The intended usage for this credential object. The value of 1720 this parameter must be one of: 1721 GSSCredential.INITIATE_AND_ACCEPT(0), 1722 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1724 7.1.12. createCredential 1726 public abstract GSSCredential createCredential(GSSName aName, 1727 int lifetime, Oid[] mechs, int usage) 1728 throws GSSException 1730 Factory method for acquiring credentials over a set of mechanisms. 1731 Acquires credentials for each of the mechanisms specified in the 1732 array called mechs. To determine the list of mechanisms' for which 1733 the acquisition of credentials succeeded, the caller should use the 1734 GSSCredential.getMechs() method. 1736 Parameters: 1738 aName Name of the principal for whom this credential is to be 1739 acquired. Use "null" to specify the default principal. 1741 lifetime The number of seconds that credentials should remain 1742 valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the 1743 credentials have the maximum permitted lifetime. Use 1744 GSSCredential.DEFAULT_LIFETIME to request default credential 1745 lifetime. 1747 mechs The array of mechanisms over which the credential is to be 1748 acquired. Use "(Oid[]) null" for requesting a system specific 1749 default set of mechanisms. 1751 usage The intended usage for this credential object. The value of 1752 this parameter must be one of: 1753 GSSCredential.INITIATE_AND_ACCEPT(0), 1754 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1756 7.1.13. createContext 1758 public abstract GSSContext createContext(GSSName peer, Oid mech, 1759 GSSCredential myCred, int lifetime) 1760 throws GSSException 1762 Factory method for creating a context on the initiator's side. 1763 Context flags may be modified through the mutator methods prior to 1764 calling GSSContext.initSecContext(). 1766 Parameters: 1768 peer Name of the target peer. 1770 mech Oid of the desired mechanism. Use "(Oid) null" to request 1771 the default mechanism. 1773 myCred Credentials of the initiator. Use "null" to act as a 1774 default initiator principal. 1776 lifetime The request lifetime, in seconds, for the context. Use 1777 GSSContext.INDEFINITE_LIFETIME and GSSContext.DEFAULT_LIFETIME to 1778 request indefinite or default context lifetime. 1780 7.1.14. createContext 1782 public abstract GSSContext createContext(GSSCredential myCred) 1783 throws GSSException 1785 Factory method for creating a context on the acceptor' side. The 1786 context's properties will be determined from the input token supplied 1787 to the accept method. 1789 Parameters: 1791 myCred Credentials for the acceptor. Use "null" to act as a 1792 default acceptor principal. 1794 7.1.15. createContext 1796 public abstract GSSContext createContext(byte[] interProcessToken) 1797 throws GSSException 1799 Factory method for creating a previously exported context. The 1800 context properties will be determined from the input token and can't 1801 be modified through the set methods. 1803 Parameters: 1805 interProcessToken The token previously emitted from the export 1806 method. 1808 7.1.16. addProviderAtFront 1810 public abstract void addProviderAtFront(Provider p, Oid mech) 1811 throws GSSException 1813 This method is used to indicate to the GSSManager that the 1814 application would like a particular provider to be used ahead of all 1815 others when support is desired for the given mechanism. When a value 1816 of null is used instead of an Oid for the mechanism, the GSSManager 1817 must use the indicated provider ahead of all others no matter what 1818 the mechanism is. Only when the indicated provider does not support 1819 the needed mechanism should the GSSManager move on to a different 1820 provider. 1822 Calling this method repeatedly preserves the older settings but 1823 lowers them in preference thus forming an ordered list of provider 1824 and Oid pairs that grows at the top. 1826 Calling addProviderAtFront with a null Oid will remove all previous 1827 preferences that were set for this provider in the GSSManager 1828 instance. Calling addProviderAtFront with a non-null Oid will remove 1829 any previous preference that was set using this mechanism and this 1830 provider together. 1832 If the GSSManager implementation does not support an SPI with a 1833 pluggable provider architecture it should throw a GSSException with 1834 the status code GSSException.UNAVAILABLE to indicate that the 1835 operation is unavailable. 1837 Parameters: 1839 p The provider instance that should be used whenever support is 1840 needed for mech. 1842 mech The mechanism for which the provider is being set 1844 7.1.17. Example Code 1846 Suppose an application desired that the provider A always be checked 1847 first when any mechanism is needed, it would call: 1849 GSSManager mgr = GSSManager.getInstance(); 1850 // mgr may at this point have its own pre-configured list 1851 // of provider preferences. The following will prepend to 1852 // any such list: 1854 mgr.addProviderAtFront(A, null); 1856 Now if it also desired that the mechanism of Oid m1 always be 1857 obtained from the provider B before the previously set A was checked, 1858 it would call: 1860 mgr.addProviderAtFront(B, m1); 1862 The GSSManager would then first check with B if m1 was needed. In 1863 case B did not provide support for m1, the GSSManager would continue 1864 on to check with A. If any mechanism m2 is needed where m2 is 1865 different from m1 then the GSSManager would skip B and check with A 1866 directly. 1868 Suppose at a later time the following call is made to the same 1869 GSSManager instance: 1871 mgr.addProviderAtFront(B, null) 1873 then the previous setting with the pair (B, m1) is subsumed by this 1874 and should be removed. Effectively the list of preferences now 1875 becomes {(B, null), (A, null), ... //followed by the pre-configured 1876 list. 1878 Please note, however, that the following call: 1880 mgr.addProviderAtFront(A, m3) 1882 does not subsume the previous setting of (A, null) and the list will 1883 effectively become {(A, m3), (B, null), (A, null), ...} 1885 7.1.18. addProviderAtEnd 1887 public abstract void addProviderAtEnd(Provider p, Oid mech) 1888 throws GSSException 1890 This method is used to indicate to the GSSManager that the 1891 application would like a particular provider to be used if no other 1892 provider can be found that supports the given mechanism. When a 1893 value of null is used instead of an Oid for the mechanism, the 1894 GSSManager must use the indicated provider for any mechanism. 1896 Calling this method repeatedly preserves the older settings but 1897 raises them above newer ones in preference thus forming an ordered 1898 list of providers and Oid pairs that grows at the bottom. Thus the 1899 older provider settings will be utilized first before this one is. 1901 If there are any previously existing preferences that conflict with 1902 the preference being set here, then the GSSManager should ignore this 1903 request. 1905 If the GSSManager implementation does not support an SPI with a 1906 pluggable provider architecture it should throw a GSSException with 1907 the status code GSSException.UNAVAILABLE to indicate that the 1908 operation is unavailable. 1910 Parameters: 1912 p The provider instance that should be used whenever support is 1913 needed for mech. 1915 mech The mechanism for which the provider is being set 1917 7.1.19. Example Code 1919 Suppose an application desired that when a mechanism of Oid m1 is 1920 needed the system default providers always be checked first, and only 1921 when they do not support m1 should a provider A be checked. It would 1922 then make the call: 1924 GSSManager mgr = GSSManager.getInstance(); 1926 mgr.addProviderAtEnd(A, m1); 1928 Now, if it also desired that for all mechanisms the provider B be 1929 checked after all configured providers have been checked, it would 1930 then call: 1932 mgr.addProviderAtEnd(B, null); 1934 Effectively the list of preferences now becomes {..., (A, m1), (B, 1935 null)}. 1937 Suppose at a later time the following call is made to the same 1938 GSSManager instance: 1940 mgr.addProviderAtEnd(B, m2) 1942 then the previous setting with the pair (B, null) subsumes this and 1943 therefore this request should be ignored. The same would happen if a 1944 request is made for the already existing pairs of (A, m1) or (B, 1945 null). 1947 Please note, however, that the following call: 1949 mgr.addProviderAtEnd(A, null) 1951 is not subsumed by the previous setting of (A, m1) and the list will 1952 effectively become {..., (A, m1), (B, null), (A, null)} 1954 7.2. public interface GSSName 1956 This interface encapsulates a single GSS-API principal entity. 1957 Different name formats and their definitions are identified with 1958 universal Object Identifiers (Oids). The format of the names can be 1959 derived based on the unique oid of its namespace type. 1961 7.2.1. Example Code 1963 Included below are code examples utilizing the GSSName interface. 1964 The code below creates a GSSName, converts it to a mechanism name 1965 (MN), performs a comparison, obtains a printable representation of 1966 the name, exports it and then re-imports to obtain a new GSSName. 1968 GSSManager mgr = GSSManager.getInstance(); 1970 // create a host based service name 1971 GSSName name = mgr.createName("service@host", 1972 GSSName.NT_HOSTBASED_SERVICE); 1974 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 1976 GSSName mechName = name.canonicalize(krb5); 1978 // the above two steps are equivalent to the following 1979 GSSName mechName = mgr.createName("service@host", 1980 GSSName.NT_HOSTBASED_SERVICE, krb5); 1982 // perform name comparison 1983 if (name.equals(mechName)) 1984 print("Names are equals."); 1986 // obtain textual representation of name and its printable 1987 // name type 1988 print(mechName.toString() + 1989 mechName.getStringNameType().toString()); 1991 // export and re-import the name 1992 byte[] exportName = mechName.export(); 1994 // create a new name object from the exported buffer 1995 GSSName newName = mgr.createName(exportName, 1996 GSSName.NT_EXPORT_NAME); 1998 7.2.2. Static Constants 2000 public static final Oid NT_HOSTBASED_SERVICE 2002 Oid indicating a host-based service name form. It is used to 2003 represent services associated with host computers. This name form is 2004 constructed using two elements, "service" and "hostname", as follows: 2006 service@hostname 2008 Values for the "service" element are registered with the IANA. It 2009 represents the following value: { iso(1) member-body(2) Unites 2010 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2011 service_name(4) } 2013 public static final Oid NT_USER_NAME 2015 Name type to indicate a named user on a local system. It represents 2016 the following value: { iso(1) member-body(2) United States(840) 2017 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2019 public static final Oid NT_MACHINE_UID_NAME 2021 Name type to indicate a numeric user identifier corresponding to a 2022 user on a local system. (e.g. Uid). It represents the following 2023 value: { iso(1) member-body(2) United States(840) mit(113554) 2024 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2026 public static final Oid NT_STRING_UID_NAME 2028 Name type to indicate a string of digits representing the numeric 2029 user identifier of a user on a local system. It represents the 2030 following value: { iso(1) member-body(2) United States(840) 2031 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2033 public static final Oid NT_ANONYMOUS 2035 Name type for representing an anonymous entity. It represents the 2036 following value: { iso(1), org(3), dod(6), internet(1), security(5), 2037 nametypes(6), gss-anonymous-name(3) } 2039 public static final Oid NT_EXPORT_NAME 2041 Name type used to indicate an exported name produced by the export 2042 method. It represents the following value: { iso(1), org(3), dod(6), 2043 internet(1), security(5), nametypes(6), gss-api-exported-name(4) } 2045 7.2.3. equals 2047 public boolean equals(GSSName another) throws GSSException 2049 Compares two GSSName objects to determine whether they refer to the 2050 same entity. This method may throw a GSSException when the names 2051 cannot be compared. If either of the names represents an anonymous 2052 entity, the method will return "false". 2054 Parameters: 2056 another GSSName object to compare with. 2058 7.2.4. equals 2060 public boolean equals(Object another) 2062 A variation of the equals method described in 7.2.3 that is provided 2063 to override the Object.equals() method that the implementing class 2064 will inherit. The behavior is exactly the same as that in 7.2.3 2065 except that no GSSException is thrown; instead, false will be 2066 returned in the situation where an error occurs. (Note that the Java 2067 language specification requires that two objects that are equal 2068 according to the equals(Object) method must return the same integer 2069 result when the hashCode() method is called on them.) 2071 Parameters: 2073 another GSSName object to compare with. 2075 7.2.5. canonicalize 2077 public GSSName canonicalize(Oid mech) throws GSSException 2079 Creates a mechanism name (MN) from an arbitrary internal name. This 2080 is equivalent to using the factory methods described in 7.1.8 or 2081 7.1.9 that take the mechanism name as one of their parameters. 2083 Parameters: 2085 mech The oid for the mechanism for which the canonical form of the 2086 name is requested. 2088 7.2.6. export 2090 public byte[] export() throws GSSException 2092 Returns a canonical contiguous byte representation of a mechanism 2093 name (MN), suitable for direct, byte by byte comparison by 2094 authorization functions. If the name is not an MN, implementations 2095 may throw a GSSException with the NAME_NOT_MN status code. If an 2096 implementation chooses not to throw an exception, it should use some 2097 system specific default mechanism to canonicalize the name and then 2098 export it. The format of the header of the output buffer is 2099 specified in RFC 2743 [GSSAPIv2-UPDATE]. 2101 7.2.7. toString 2103 public String toString() 2105 Returns a textual representation of the GSSName object. To retrieve 2106 the printed name format, which determines the syntax of the returned 2107 string, the getStringNameType method can be used. 2109 7.2.8. getStringNameType 2111 public Oid getStringNameType() throws GSSException 2113 Returns the oid representing the type of name returned through the 2114 toString method. Using this oid, the syntax of the printable name 2115 can be determined. 2117 7.2.9. isAnonymous 2119 public boolean isAnonymous() 2121 Tests if this name object represents an anonymous entity. Returns 2122 "true" if this is an anonymous name. 2124 7.2.10. isMN 2126 public boolean isMN() 2128 Tests if this name object contains only one mechanism element and is 2129 thus a mechanism name as defined by RFC 2743 [GSSAPIv2-UPDATE]. 2131 7.3. public interface GSSCredential implements Cloneable 2133 This interface encapsulates the GSS-API credentials for an entity. A 2134 credential contains all the necessary cryptographic information to 2135 enable the creation of a context on behalf of the entity that it 2136 represents. It may contain multiple, distinct, mechanism specific 2137 credential elements, each containing information for a specific 2138 security mechanism, but all referring to the same entity. 2140 A credential may be used to perform context initiation, acceptance, 2141 or both. 2143 GSS-API implementations must impose a local access-control policy on 2144 callers to prevent unauthorized callers from acquiring credentials to 2145 which they are not entitled. GSS-API credential creation is not 2146 intended to provide a "login to the network" function, as such a 2147 function would involve the creation of new credentials rather than 2148 merely acquiring a handle to existing credentials. Such functions, 2149 if required, should be defined in implementation-specific extensions 2150 to the API. 2152 If credential acquisition is time-consuming for a mechanism, the 2153 mechanism may choose to delay the actual acquisition until the 2154 credential is required (e.g. by GSSContext). Such mechanism- 2155 specific implementation decisions should be invisible to the calling 2156 application; thus the query methods immediately following the 2157 creation of a credential object must return valid credential data, 2158 and may therefore incur the overhead of a deferred credential 2159 acquisition. 2161 Applications will create a credential object passing the desired 2162 parameters. The application can then use the query methods to obtain 2163 specific information about the instantiated credential object 2164 (equivalent to the gss_inquire routines). When the credential is no 2165 longer needed, the application should call the dispose (equivalent to 2166 gss_release_cred) method to release any resources held by the 2167 credential object and to destroy any cryptographically sensitive 2168 information. 2170 Classes implementing this interface also implement the Cloneable 2171 interface. This indicates the the class will support the clone() 2172 method that will allow the creation of duplicate credentials. This 2173 is useful when called just before the add() call to retain a copy of 2174 the original credential. 2176 7.3.1. Example Code 2178 This example code demonstrates the creation of a GSSCredential 2179 implementation for a specific entity, querying of its fields, and its 2180 release when it is no longer needed. 2182 GSSManager mgr = GSSManager.getInstance(); 2184 // start by creating a name object for the entity 2185 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2187 // now acquire credentials for the entity 2188 GSSCredential cred = mgr.createCredential(name, 2189 GSSCredential.ACCEPT_ONLY); 2191 // display credential information - name, remaining lifetime, 2192 // and the mechanisms it has been acquired over 2193 print(cred.getName().toString()); 2194 print(cred.getRemainingLifetime()); 2196 Oid[] mechs = cred.getMechs(); 2197 if (mechs != null) { 2198 for (int i = 0; i < mechs.length; i++) 2199 print(mechs[i].toString()); 2200 } 2201 // release system resources held by the credential 2202 cred.dispose(); 2204 7.3.2. Static Constants 2206 public static final int INITIATE_AND_ACCEPT 2208 Credential usage flag requesting that it be able to be used for both 2209 context initiation and acceptance. The value of this constant is 0. 2211 public static final int INITIATE_ONLY 2213 Credential usage flag requesting that it be able to be used for 2214 context initiation only. The value of this constant is 1. 2216 public static final int ACCEPT_ONLY 2218 Credential usage flag requesting that it be able to be used for 2219 context acceptance only. The value of this constant is 2. 2221 public static final int DEFAULT_LIFETIME 2223 A lifetime constant representing the default credential lifetime. 2224 The value of this constant is 0. 2226 public static final int INDEFINITE_LIFETIME 2228 A lifetime constant representing indefinite credential lifetime. The 2229 value of this constant is the maximum integer value in Java - 2230 Integer.MAX_VALUE. 2232 7.3.3. dispose 2234 public void dispose() throws GSSException 2236 Releases any sensitive information that the GSSCredential object may 2237 be containing. Applications should call this method as soon as the 2238 credential is no longer needed to minimize the time any sensitive 2239 information is maintained. 2241 7.3.4. getName 2243 public GSSName getName() throws GSSException 2245 Retrieves the name of the entity that the credential asserts. 2247 7.3.5. getName 2248 public GSSName getName(Oid mechOID) throws GSSException 2250 Retrieves a mechanism name of the entity that the credential asserts. 2251 Equivalent to calling canonicalize() on the name returned by 7.3.4. 2253 Parameters: 2255 mechOID The mechanism for which information should be returned. 2257 7.3.6. getRemainingLifetime 2259 public int getRemainingLifetime() throws GSSException 2261 Returns the remaining lifetime in seconds for a credential. The 2262 remaining lifetime is the minimum lifetime for any of the underlying 2263 credential mechanisms. A return value of 2264 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2265 not expire. A return value of 0 indicates that the credential is 2266 already expired. 2268 7.3.7. getRemainingInitLifetime 2270 public int getRemainingInitLifetime(Oid mech) throws GSSException 2272 Returns the remaining lifetime is seconds for the credential to 2273 remain capable of initiating security contexts under the specified 2274 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2275 indicates that the credential does not expire for context initiation. 2276 A return value of 0 indicates that the credential is already expired. 2278 Parameters: 2280 mechOID The mechanism for which information should be returned. 2282 7.3.8. getRemainingAcceptLifetime 2284 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2286 Returns the remaining lifetime is seconds for the credential to 2287 remain capable of accepting security contexts under the specified 2288 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2289 indicates that the credential does not expire for context acceptance. 2290 A return value of 0 indicates that the credential is already expired. 2292 Parameters: 2294 mechOID The mechanism for which information should be returned. 2296 7.3.9. getUsage 2298 public int getUsage() throws GSSException 2300 Returns the credential usage flag as a union over all mechanisms. 2301 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2302 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2304 7.3.10. getUsage 2306 public int getUsage(Oid mechOID) throws GSSException 2308 Returns the credential usage flag for the specified mechanism only. 2309 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2310 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2312 Parameters: 2314 mechOID The mechanism for which information should be returned. 2316 7.3.11. getMechs 2318 public Oid[] getMechs() throws GSSException 2320 Returns an array of mechanisms supported by this credential. 2322 7.3.12. add 2324 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2325 Oid mech, int usage) throws GSSException 2327 Adds a mechanism specific credential-element to an existing 2328 credential. This method allows the construction of credentials one 2329 mechanism at a time. 2331 This routine is envisioned to be used mainly by context acceptors 2332 during the creation of acceptance credentials which are to be used 2333 with a variety of clients using different security mechanisms. 2335 This routine adds the new credential element "in-place". To add the 2336 element in a new credential, first call clone() to obtain a copy of 2337 this credential, then call its add() method. 2339 Parameters: 2341 aName Name of the principal for whom this credential is to be 2342 acquired. Use "null" to specify the default principal. 2344 initLifetime The number of seconds that credentials should remain 2345 valid for initiating of security contexts. Use 2346 GSSCredential.INDEFINITE_LIFETIME to request that the credentials 2347 have the maximum permitted lifetime. Use 2348 GSSCredential.DEFAULT_LIFETIME to request default credential 2349 lifetime. 2351 acceptLifetime The number of seconds that credentials should 2352 remain valid for accepting of security contexts. Use 2353 GSSCredential.INDEFINITE_LIFETIME to request that the credentials 2354 have the maximum permitted lifetime. Use 2355 GSSCredential.DEFAULT_LIFETIME to request default credential 2356 lifetime. 2358 mech The mechanisms over which the credential is to be acquired. 2360 usage The intended usage for this credential object. The value of 2361 this parameter must be one of: 2362 GSSCredential.INITIATE_AND_ACCEPT(0), 2363 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 2365 7.3.13. equals 2367 public boolean equals(Object another) 2369 Tests if this GSSCredential refers to the same entity as the supplied 2370 object. The two credentials must be acquired over the same 2371 mechanisms and must refer to the same principal. Returns "true" if 2372 the two GSSCredentials refer to the same entity; "false" otherwise. 2373 (Note that the Java language specification [JLS] requires that two 2374 objects that are equal according to the equals(Object) method must 2375 return the same integer result when the hashCode() method is called 2376 on them.) 2378 Parameters: 2380 another Another GSSCredential object for comparison. 2382 7.4. public interface GSSContext 2384 This interface encapsulates the GSS-API security context and provides 2385 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2386 available over the context. Security contexts are established 2387 between peers using locally acquired credentials. Multiple contexts 2388 may exist simultaneously between a pair of peers, using the same or 2389 different set of credentials. GSS-API functions in a manner 2390 independent of the underlying transport protocol and depends on its 2391 calling application to transport its tokens between peers. 2393 Before the context establishment phase is initiated, the context 2394 initiator may request specific characteristics desired of the 2395 established context. These can be set using the set methods. After 2396 the context is established, the caller can check the actual 2397 characteristic and services offered by the context using the query 2398 methods. 2400 The context establishment phase begins with the first call to the 2401 init method by the context initiator. During this phase the 2402 initSecContext and acceptSecContext methods will produce GSS-API 2403 authentication tokens which the calling application needs to send to 2404 its peer. If an error occurs at any point, an exception will get 2405 thrown and the code will start executing in a catch block. If not, 2406 the normal flow of code continues and the application can make a call 2407 to the isEstablished() method. If this method returns false it 2408 indicates that a token is needed from its peer in order to continue 2409 the context establishment phase. A return value of true signals that 2410 the local end of the context is established. This may still require 2411 that a token be sent to the peer, if one is produced by GSS-API. 2412 During the context establishment phase, the isProtReady() method may 2413 be called to determine if the context can be used for the per-message 2414 operations. This allows applications to use per-message operations 2415 on contexts which aren't fully established. 2417 After the context has been established or the isProtReady() method 2418 returns "true", the query routines can be invoked to determine the 2419 actual characteristics and services of the established context. The 2420 application can also start using the per-message methods of wrap and 2421 getMIC to obtain cryptographic operations on application supplied 2422 data. 2424 When the context is no longer needed, the application should call 2425 dispose to release any system resources the context may be using. 2427 7.4.1. Example Code 2429 The example code presented below demonstrates the usage of the 2430 GSSContext interface for the initiating peer. Different operations 2431 on the GSSContext object are presented, including: object 2432 instantiation, setting of desired flags, context establishment, query 2433 of actual context flags, per-message operations on application data, 2434 and finally context deletion. 2436 GSSManager mgr = GSSManager.getInstance(); 2438 // start by creating the name for a service entity 2439 GSSName targetName = mgr.createName("service@host", 2440 GSSName.NT_HOSTBASED_SERVICE); 2442 // create a context using default credentials for the above entity 2443 // and the implementation specific default mechanism 2444 GSSContext context = mgr.createContext(targetName, 2445 null, /* default mechanism */ 2446 null, /* default credentials */ 2447 GSSContext.INDEFINITE_LIFETIME); 2449 // set desired context options - all others are false by default 2450 context.requestConf(true); 2451 context.requestMutualAuth(true); 2452 context.requestReplayDet(true); 2453 context.requestSequenceDet(true); 2455 // establish a context between peers - using byte arrays 2456 byte[]inTok = new byte[0]; 2458 try { 2459 do { 2460 byte[] outTok = context.initSecContext(inTok, 0, 2461 inTok.length); 2463 // send the token if present 2464 if (outTok != null) 2465 sendToken(outTok); 2467 // check if we should expect more tokens 2468 if (context.isEstablished()) 2469 break; 2471 // another token expected from peer 2472 inTok = readToken(); 2474 } while (true); 2476 } catch (GSSException e) { 2477 print("GSSAPI error: " + e.getMessage()); 2478 } 2480 // display context information 2481 print("Remaining lifetime in seconds = " + context.getLifetime()); 2482 print("Context mechanism = " + context.getMech().toString()); 2483 print("Initiator = " + context.getSrcName().toString()); 2484 print("Acceptor = " + context.getTargName().toString()); 2486 if (context.getConfState()) 2487 print("Confidentiality security service available"); 2489 if (context.getIntegState()) 2490 print("Integrity security service available"); 2492 // perform wrap on an application supplied message, appMsg, 2493 // using QOP = 0, and requesting privacy service 2494 byte[] appMsg ... 2496 MessageProp mProp = new MessageProp(0, true); 2498 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2500 if (mProp.getPrivacy()) 2501 print("Message protected with privacy."); 2503 sendToken(tok); 2505 // release the local-end of the context 2506 context.dispose(); 2508 7.4.2. Static Constants 2510 public static final int DEFAULT_LIFETIME 2512 A lifetime constant representing the default context lifetime. The 2513 value of this constant is 0. 2515 public static final int INDEFINITE_LIFETIME 2517 A lifetime constant representing indefinite context lifetime. The 2518 value of this constant is the maximum integer value in Java - 2519 Integer.MAX_VALUE. 2521 7.4.3. initSecContext 2523 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2524 throws GSSException 2526 Called by the context initiator to start the context creation 2527 process. This is equivalent to the stream based method except that 2528 the token buffers are handled as byte arrays instead of using stream 2529 objects. This method may return an output token which the 2530 application will need to send to the peer for processing by the 2531 accept call. Typically, the application would do so by calling the 2532 flush() method on an OutputStream that encapsulates the connection 2533 between the two peers. The application can call isEstablished() to 2534 determine if the context establishment phase is complete for this 2535 peer. A return value of "false" from isEstablished() indicates that 2536 more tokens are expected to be supplied to the initSecContext() 2537 method. Note that it is possible that the initSecContext() method 2538 return a token for the peer, and isEstablished() return "true" also. 2539 This indicates that the token needs to be sent to the peer, but the 2540 local end of the context is now fully established. 2542 Upon completion of the context establishment, the available context 2543 options may be queried through the get methods. 2545 Parameters: 2547 inputBuf Token generated by the peer. This parameter is ignored 2548 on the first call. 2550 offset The offset within the inputBuf where the token begins. 2552 len The length of the token within the inputBuf (starting at the 2553 offset). 2555 7.4.4. Example Code 2557 // Create a new GSSContext implementation object. 2558 // GSSContext wrapper implements interface GSSContext. 2559 GSSContext context = mgr.createContext(...); 2561 byte[] inTok = new byte[0]; 2563 try { 2564 do { 2565 byte[] outTok = context.initSecContext(inTok, 0, 2566 inTok.length); 2568 // send the token if present 2569 if (outTok != null) 2570 sendToken(outTok); 2572 // check if we should expect more tokens 2573 if (context.isEstablished()) 2574 break; 2576 // another token expected from peer 2577 inTok = readToken(); 2578 } while (true); 2580 } catch (GSSException e) { 2581 print("GSSAPI error: " + e.getMessage()); 2582 } 2584 7.4.5. initSecContext 2585 public int initSecContext(InputStream inStream, 2586 OutputStream outStream) throws GSSException 2588 Called by the context initiator to start the context creation 2589 process. This is equivalent to the byte array based method. This 2590 method may write an output token to the outStream, which the 2591 application will need to send to the peer for processing by the 2592 accept call. Typically, the application would do so by calling the 2593 flush() method on an OutputStream that encapsulates the connection 2594 between the two peers. The application can call isEstablished() to 2595 determine if the context establishment phase is complete for this 2596 peer. A return value of "false" from isEstablished indicates that 2597 more tokens are expected to be supplied to the initSecContext method. 2598 Note that it is possible that the initSecContext() method return a 2599 token for the peer, and isEstablished() return "true" also. This 2600 indicates that the token needs to be sent to the peer, but the local 2601 end of the context is now fully established. 2603 The GSS-API authentication tokens contain a definitive start and end. 2604 This method will attempt to read one of these tokens per invocation, 2605 and may block on the stream if only part of the token is available. 2607 Upon completion of the context establishment, the available context 2608 options may be queried through the get methods. 2610 Parameters: 2612 inStream Contains the token generated by the peer. This parameter 2613 is ignored on the first call. 2615 outStream Output stream where the output token will be written. 2616 During the final stage of context establishment, there may be no 2617 bytes written. 2619 7.4.6. Example Code 2621 This sample code merely demonstrates the token exchange during the 2622 context establishment phase. It is expected that most Java 2623 applications will use custom implementations of the Input and Output 2624 streams that encapsulate the communication routines. For instance, a 2625 simple read on the application InputStream, when called by the 2626 Context, might cause a token to be read from the peer, and a simple 2627 flush() on the application OutputStream might cause a previously 2628 written token to be transmitted to the peer. 2630 // Create a new GSSContext implementation object. 2631 // GSSContext wrapper implements interface GSSContext. 2632 GSSContext context = mgr.createContext(...); 2633 // use standard java.io stream objects 2634 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2635 ByteArrayInputStream is = null; 2637 try { 2638 do { 2639 context.initSecContext(is, os); 2641 // send token if present 2642 if (os.size() > 0) 2643 sendToken(os); 2645 // check if we should expect more tokens 2646 if (context.isEstablished()) 2647 break; 2649 // another token expected from peer 2650 is = recvToken(); 2652 } while (true); 2654 } catch (GSSException e) { 2655 print("GSSAPI error: " + e.getMessage()); 2656 } 2658 7.4.7. acceptSecContext 2660 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2661 throws GSSException 2663 Called by the context acceptor upon receiving a token from the peer. 2664 This call is equivalent to the stream based method except that the 2665 token buffers are handled as byte arrays instead of using stream 2666 objects. 2668 This method may return an output token which the application will 2669 need to send to the peer for further processing by the init call. 2671 "null" return value indicates that no token needs to be sent to the 2672 peer. The application can call isEstablished() to determine if the 2673 context establishment phase is complete for this peer. A return 2674 value of "false" from isEstablished() indicates that more tokens are 2675 expected to be supplied to this method. 2677 Note that it is possible that acceptSecContext() return a token for 2678 the peer, and isEstablished() return "true" also. This indicates 2679 that the token needs to be sent to the peer, but the local end of the 2680 context is now fully established. 2682 Upon completion of the context establishment, the available context 2683 options may be queried through the get methods. 2685 Parameters: 2687 inTok Token generated by the peer. 2689 offset The offset within the inTok where the token begins. 2691 len The length of the token within the inTok (starting at the 2692 offset). 2694 7.4.8. Example Code 2696 // acquire server credentials 2697 GSSCredential server = mgr.createCredential(...); 2699 // create acceptor GSS-API context from the default provider 2700 GSSContext context = mgr.createContext(server, null); 2702 try { 2703 do { 2704 byte[] inTok = readToken(); 2706 byte[] outTok = context.acceptSecContext(inTok, 0, 2707 inTok.length); 2709 // possibly send token to peer 2710 if (outTok != null) 2711 sendToken(outTok); 2713 // check if local context establishment is complete 2714 if (context.isEstablished()) 2715 break; 2716 } while (true); 2718 } catch (GSSException e) { 2719 print("GSS-API error: " + e.getMessage()); 2720 } 2722 7.4.9. acceptSecContext 2724 public void acceptSecContext(InputStream inStream, 2725 OutputStream outStream) throws GSSException 2727 Called by the context acceptor upon receiving a token from the peer. 2728 This call is equivalent to the byte array method. It may write an 2729 output token to the outStream, which the application will need to 2730 send to the peer for processing by its initSecContext method. 2731 Typically, the application would do so by calling the flush() method 2732 on an OutputStream that encapsulates the connection between the two 2733 peers. The application can call isEstablished() to determine if the 2734 context establishment phase is complete for this peer. A return 2735 value of "false" from isEstablished() indicates that more tokens are 2736 expected to be supplied to this method. 2738 Note that it is possible that acceptSecContext() return a token for 2739 the peer, and isEstablished() return "true" also. This indicates 2740 that the token needs to be sent to the peer, but the local end of the 2741 context is now fully established. 2743 The GSS-API authentication tokens contain a definitive start and end. 2744 This method will attempt to read one of these tokens per invocation, 2745 and may block on the stream if only part of the token is available. 2747 Upon completion of the context establishment, the available context 2748 options may be queried through the get methods. 2750 Parameters: 2752 inStream Contains the token generated by the peer. 2754 outStream Output stream where the output token will be written. 2755 During the final stage of context establishment, there may be no 2756 bytes written. 2758 7.4.10. Example Code 2760 This sample code merely demonstrates the token exchange during the 2761 context establishment phase. It is expected that most Java 2762 applications will use custom implementations of the Input and Output 2763 streams that encapsulate the communication routines. For instance, a 2764 simple read on the application InputStream, when called by the 2765 Context, might cause a token to be read from the peer, and a simple 2766 flush() on the application OutputStream might cause a previously 2767 written token to be transmitted to the peer. 2769 // acquire server credentials 2770 GSSCredential server = mgr.createCredential(...); 2772 // create acceptor GSS-API context from the default provider 2773 GSSContext context = mgr.createContext(server, null); 2775 // use standard java.io stream objects 2776 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2777 ByteArrayInputStream is = null; 2778 try { 2779 do { 2781 is = recvToken(); 2783 context.acceptSecContext(is, os); 2785 // possibly send token to peer 2786 if (os.size() > 0) 2787 sendToken(os); 2789 // check if local context establishment is complete 2790 if (context.isEstablished()) 2791 break; 2792 } while (true); 2794 } catch (GSSException e) { 2795 print("GSS-API error: " + e.getMessage()); 2796 } 2798 7.4.11. isEstablished 2800 public boolean isEstablished() 2802 Used during context establishment to determine the state of the 2803 context. Returns "true" if this is a fully established context on 2804 the caller's side and no more tokens are needed from the peer. 2805 Should be called after a call to initSecContext() or 2806 acceptSecContext() when no GSSException is thrown. 2808 7.4.12. dispose 2810 public void dispose() throws GSSException 2812 Releases any system resources and cryptographic information stored in 2813 the context object. This will invalidate the context. 2815 7.4.13. getWrapSizeLimit 2817 public int getWrapSizeLimit(int qop, boolean confReq, 2818 int maxTokenSize) throws GSSException 2820 Returns the maximum message size that, if presented to the wrap 2821 method with the same confReq and qop parameters, will result in an 2822 output token containing no more than the maxTokenSize bytes. 2824 This call is intended for use by applications that communicate over 2825 protocols that impose a maximum message size. It enables the 2826 application to fragment messages prior to applying protection. 2828 GSS-API implementations are recommended but not required to detect 2829 invalid QOP values when getWrapSizeLimit is called. This routine 2830 guarantees only a maximum message size, not the availability of 2831 specific QOP values for message protection. 2833 Successful completion of this call does not guarantee that wrap will 2834 be able to protect a message of the computed length, since this 2835 ability may depend on the availability of system resources at the 2836 time that wrap is called. However, if the implementation itself 2837 imposes an upper limit on the length of messages that may be 2838 processed by wrap, the implementation should not return a value that 2839 is greater than this length. 2841 Parameters: 2843 qop Indicates the level of protection wrap will be asked to 2844 provide. 2846 confReq Indicates if wrap will be asked to provide privacy 2847 service. 2849 maxTokenSize The desired maximum size of the token emitted by 2850 wrap. 2852 7.4.14. wrap 2854 public byte[] wrap(byte[] inBuf, int offset, int len, 2855 MessageProp msgProp) throws GSSException 2857 Applies per-message security services over the established security 2858 context. The method will return a token with a cryptographic MIC and 2859 may optionally encrypt the specified inBuf. This method is 2860 equivalent in functionality to its stream counterpart. The returned 2861 byte array will contain both the MIC and the message. 2863 The MessageProp object is instantiated by the application and used to 2864 specify a QOP value which selects cryptographic algorithms, and a 2865 privacy service to optionally encrypt the message. The underlying 2866 mechanism that is used in the call may not be able to provide the 2867 privacy service. It sets the actual privacy service that it does 2868 provide in this MessageProp object which the caller should then query 2869 upon return. If the mechanism is not able to provide the requested 2870 QOP, it throws a GSSException with the BAD_QOP code. 2872 Since some application-level protocols may wish to use tokens emitted 2873 by wrap to provide "secure framing", implementations should support 2874 the wrapping of zero-length messages. 2876 The application will be responsible for sending the token to the 2877 peer. 2879 Parameters: 2881 inBuf Application data to be protected. 2883 offset The offset within the inBuf where the data begins. 2885 len The length of the data within the inBuf (starting at the 2886 offset). 2888 msgProp Instance of MessageProp that is used by the application to 2889 set the desired QOP and privacy state. Set the desired QOP to 0 2890 to request the default QOP. Upon return from this method, this 2891 object will contain the the actual privacy state that was applied 2892 to the message by the underlying mechanism. 2894 7.4.15. wrap 2896 public void wrap(InputStream inStream, OutputStream outStream, 2897 MessageProp msgProp) throws GSSException 2899 Allows to apply per-message security services over the established 2900 security context. The method will produce a token with a 2901 cryptographic MIC and may optionally encrypt the message in inStream. 2902 The outStream will contain both the MIC and the message. 2904 The MessageProp object is instantiated by the application and used to 2905 specify a QOP value which selects cryptographic algorithms, and a 2906 privacy service to optionally encrypt the message. The underlying 2907 mechanism that is used in the call may not be able to provide the 2908 privacy service. It sets the actual privacy service that it does 2909 provide in this MessageProp object which the caller should then query 2910 upon return. If the mechanism is not able to provide the requested 2911 QOP, it throws a GSSException with the BAD_QOP code. 2913 Since some application-level protocols may wish to use tokens emitted 2914 by wrap to provide "secure framing", implementations should support 2915 the wrapping of zero-length messages. 2917 The application will be responsible for sending the token to the 2918 peer. 2920 Parameters: 2922 inStream Input stream containing the application data to be 2923 protected. 2925 outStream The output stream to write the protected message to. 2926 The application is responsible for sending this to the other peer 2927 for processing in its unwrap method. 2929 msgProp Instance of MessageProp that is used by the application to 2930 set the desired QOP and privacy state. Set the desired QOP to 0 2931 to request the default QOP. Upon return from this method, this 2932 object will contain the the actual privacy state that was applied 2933 to the message by the underlying mechanism. 2935 7.4.16. unwrap 2937 public byte[] unwrap(byte[] inBuf, int offset, int len, 2938 MessageProp msgProp) throws GSSException 2940 Used by the peer application to process tokens generated with the 2941 wrap call. This call is equal in functionality to its stream 2942 counterpart. The method will return the message supplied in the peer 2943 application to the wrap call, verifying the embedded MIC. 2945 The MessageProp object is instantiated by the application and is used 2946 by the underlying mechanism to return information to the caller such 2947 as the QOP, whether confidentiality was applied to the message, and 2948 other supplementary message state information. 2950 Since some application-level protocols may wish to use tokens emitted 2951 by wrap to provide "secure framing", implementations should support 2952 the wrapping and unwrapping of zero-length messages. 2954 Parameters: 2956 inBuf GSS-API wrap token received from peer. 2958 offset The offset within the inBuf where the token begins. 2960 len The length of the token within the inBuf (starting at the 2961 offset). 2963 msgProp Upon return from the method, this object will contain the 2964 applied QOP, the privacy state of the message, and supplementary 2965 information described in 5.12.3 stating whether the token was a 2966 duplicate, old, out of sequence or arriving after a gap. 2968 7.4.17. unwrap 2969 public void unwrap(InputStream inStream, OutputStream outStream, 2970 MessageProp msgProp) throws GSSException 2972 Used by the peer application to process tokens generated with the 2973 wrap call. This call is equal in functionality to its byte array 2974 counterpart. It will produce the message supplied in the peer 2975 application to the wrap call, verifying the embedded MIC. 2977 The MessageProp object is instantiated by the application and is used 2978 by the underlying mechanism to return information to the caller such 2979 as the QOP, whether confidentiality was applied to the message, and 2980 other supplementary message state information. 2982 Since some application-level protocols may wish to use tokens emitted 2983 by wrap to provide "secure framing", implementations should support 2984 the wrapping and unwrapping of zero-length messages. 2986 Parameters: 2988 inStream Input stream containing the GSS-API wrap token received 2989 from the peer. 2991 outStream The output stream to write the application message to. 2993 msgProp Upon return from the method, this object will contain the 2994 applied QOP, the privacy state of the message, and supplementary 2995 information described in 5.12.3 stating whether the token was a 2996 duplicate, old, out of sequence or arriving after a gap. 2998 7.4.18. getMIC 3000 public byte[] getMIC(byte[] inMsg, int offset, int len, 3001 MessageProp msgProp) throws GSSException 3003 Returns a token containing a cryptographic MIC for the supplied 3004 message, for transfer to the peer application. Unlike wrap, which 3005 encapsulates the user message in the returned token, only the message 3006 MIC is returned in the output token. This method is identical in 3007 functionality to its stream counterpart. 3009 Note that privacy can only be applied through the wrap call. 3011 Since some application-level protocols may wish to use tokens emitted 3012 by getMIC to provide "secure framing", implementations should support 3013 derivation of MICs from zero-length messages. 3015 Parameters: 3017 inMsg Message to generate MIC over. 3019 offset The offset within the inMsg where the token begins. 3021 len The length of the token within the inMsg (starting at the 3022 offset). 3024 msgProp Instance of MessageProp that is used by the application to 3025 set the desired QOP. Set the desired QOP to 0 in msgProp to 3026 request the default QOP. Alternatively pass in "null" for msgProp 3027 to request default QOP. 3029 7.4.19. getMIC 3031 public void getMIC(InputStream inStream, OutputStream outStream, 3032 MessageProp msgProp) throws GSSException 3034 Produces a token containing a cryptographic MIC for the supplied 3035 message, for transfer to the peer application. Unlike wrap, which 3036 encapsulates the user message in the returned token, only the message 3037 MIC is produced in the output token. This method is identical in 3038 functionality to its byte array counterpart. 3040 Note that privacy can only be applied through the wrap call. 3042 Since some application-level protocols may wish to use tokens emitted 3043 by getMIC to provide "secure framing", implementations should support 3044 derivation of MICs from zero-length messages. 3046 Parameters: 3048 inStream Input stream containing the message to generate MIC over. 3050 outStream Output stream to write the GSS-API output token to. 3052 msgProp Instance of MessageProp that is used by the application to 3053 set the desired QOP. Set the desired QOP to 0 in msgProp to 3054 request the default QOP. Alternatively pass in "null" for msgProp 3055 to request default QOP. 3057 7.4.20. verifyMIC 3059 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 3060 byte[] inMsg, int msgOffset, int msgLen, 3061 MessageProp msgProp) throws GSSException 3063 Verifies the cryptographic MIC, contained in the token parameter, 3064 over the supplied message. This method is equivalent in 3065 functionality to its stream counterpart. 3067 The MessageProp object is instantiated by the application and is used 3068 by the underlying mechanism to return information to the caller such 3069 as the QOP indicating the strength of protection that was applied to 3070 the message and other supplementary message state information. 3072 Since some application-level protocols may wish to use tokens emitted 3073 by getMIC to provide "secure framing", implementations should support 3074 the calculation and verification of MICs over zero-length messages. 3076 Parameters: 3078 inTok Token generated by peer's getMIC method. 3080 tokOffset The offset within the inTok where the token begins. 3082 tokLen The length of the token within the inTok (starting at the 3083 offset). 3085 inMsg Application message to verify the cryptographic MIC over. 3087 msgOffset The offset within the inMsg where the message begins. 3089 msgLen The length of the message within the inMsg (starting at the 3090 offset). 3092 msgProp Upon return from the method, this object will contain the 3093 applied QOP and supplementary information described in 5.12.3 3094 stating whether the token was a duplicate, old, out of sequence or 3095 arriving after a gap. The confidentiality state will be set to 3096 "false". 3098 7.4.21. verifyMIC 3100 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3101 MessageProp msgProp) throws GSSException 3103 Verifies the cryptographic MIC, contained in the token parameter, 3104 over the supplied message. This method is equivalent in 3105 functionality to its byte array counterpart. 3107 The MessageProp object is instantiated by the application and is used 3108 by the underlying mechanism to return information to the caller such 3109 as the QOP indicating the strength of protection that was applied to 3110 the message and other supplementary message state information. 3112 Since some application-level protocols may wish to use tokens emitted 3113 by getMIC to provide "secure framing", implementations should support 3114 the calculation and verification of MICs over zero-length messages. 3116 Parameters: 3118 tokStream Input stream containing the token generated by peer's 3119 getMIC method. 3121 msgStream Input stream containing the application message to 3122 verify the cryptographic MIC over. 3124 msgProp Upon return from the method, this object will contain the 3125 applied QOP and supplementary information described in 5.12.3 3126 stating whether the token was a duplicate, old, out of sequence or 3127 arriving after a gap. The confidentiality state will be set to 3128 "false". 3130 7.4.22. export 3132 public byte[] export() throws GSSException 3134 Provided to support the sharing of work between multiple processes. 3135 This routine will typically be used by the context-acceptor, in an 3136 application where a single process receives incoming connection 3137 requests and accepts security contexts over them, then passes the 3138 established context to one or more other processes for message 3139 exchange. 3141 This method deactivates the security context and creates an 3142 interprocess token which, when passed to the byte array constructor 3143 of the GSSContext interface in another process, will re-activate the 3144 context in the second process. Only a single instantiation of a 3145 given context may be active at any one time; a subsequent attempt by 3146 a context exporter to access the exported security context will fail. 3148 The implementation may constrain the set of processes by which the 3149 interprocess token may be imported, either as a function of local 3150 security policy, or as a result of implementation decisions. For 3151 example, some implementations may constrain contexts to be passed 3152 only between processes that run under the same account, or which are 3153 part of the same process group. 3155 The interprocess token may contain security-sensitive information 3156 (for example cryptographic keys). While mechanisms are encouraged to 3157 either avoid placing such sensitive information within interprocess 3158 tokens, or to encrypt the token before returning it to the 3159 application, in a typical GSS-API implementation this may not be 3160 possible. Thus the application must take care to protect the 3161 interprocess token, and ensure that any process to which the token is 3162 transferred is trustworthy. 3164 7.4.23. requestMutualAuth 3166 public void requestMutualAuth(boolean state) throws GSSException 3168 Sets the request state of the mutual authentication flag for the 3169 context. This method is only valid before the context creation 3170 process begins and only for the initiator. 3172 Parameters: 3174 state Boolean representing if mutual authentication should be 3175 requested during context establishment. 3177 7.4.24. requestReplayDet 3179 public void requestReplayDet(boolean state) throws GSSException 3181 Sets the request state of the replay detection service for the 3182 context. This method is only valid before the context creation 3183 process begins and only for the initiator. 3185 Parameters: 3187 state Boolean representing if replay detection is desired over the 3188 established context. 3190 7.4.25. requestSequenceDet 3192 public void requestSequenceDet(boolean state) throws GSSException 3194 Sets the request state for the sequence checking service of the 3195 context. This method is only valid before the context creation 3196 process begins and only for the initiator. 3198 Parameters: 3200 state Boolean representing if sequence detection is desired over 3201 the established context. 3203 7.4.26. requestCredDeleg 3205 public void requestCredDeleg(boolean state) throws GSSException 3207 Sets the request state for the credential delegation flag for the 3208 context. This method is only valid before the context creation 3209 process begins and only for the initiator. 3211 Parameters: 3213 state Boolean representing if credential delegation is desired. 3215 7.4.27. requestAnonymity 3217 public void requestAnonymity(boolean state) throws GSSException 3219 Requests anonymous support over the context. This method is only 3220 valid before the context creation process begins and only for the 3221 initiator. 3223 Parameters: 3225 state Boolean representing if anonymity support is requested. 3227 7.4.28. requestConf 3229 public void requestConf(boolean state) throws GSSException 3231 Requests that confidentiality service be available over the context. 3232 This method is only valid before the context creation process begins 3233 and only for the initiator. 3235 Parameters: 3237 state Boolean indicating if confidentiality services are to be 3238 requested for the context. 3240 7.4.29. requestInteg 3242 public void requestInteg(boolean state) throws GSSException 3244 Requests that integrity services be available over the context. This 3245 method is only valid before the context creation process begins and 3246 only for the initiator. 3248 Parameters: 3250 state Boolean indicating if integrity services are to be requested 3251 for the context. 3253 7.4.30. requestLifetime 3255 public void requestLifetime(int lifetime) throws GSSException 3256 Sets the desired lifetime for the context in seconds. This method is 3257 only valid before the context creation process begins and only for 3258 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 3259 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 3260 lifetime. 3262 Parameters: 3264 lifetime The desired context lifetime in seconds. 3266 7.4.31. setChannelBinding 3268 public void setChannelBinding(ChannelBinding cb) throws GSSException 3270 Sets the channel bindings to be used during context establishment. 3271 This method is only valid before the context creation process begins. 3273 Parameters: 3275 cb Channel bindings to be used. 3277 7.4.32. getCredDelegState 3279 public boolean getCredDelegState() 3281 Returns the state of the delegated credentials for the context. When 3282 issued before context establishment is completed or when the 3283 isProtReady method returns "false", it returns the desired state, 3284 otherwise it will indicate the actual state over the established 3285 context. 3287 7.4.33. getMutualAuthState 3289 public boolean getMutualAuthState() 3291 Returns the state of the mutual authentication option for the 3292 context. When issued before context establishment completes or when 3293 the isProtReady method returns "false", it returns the desired state, 3294 otherwise it will indicate the actual state over the established 3295 context. 3297 7.4.34. getReplayDetState 3299 public boolean getReplayDetState() 3301 Returns the state of the replay detection option for the context. 3302 When issued before context establishment completes or when the 3303 isProtReady method returns "false", it returns the desired state, 3304 otherwise it will indicate the actual state over the established 3305 context. 3307 7.4.35. getSequenceDetState 3309 public boolean getSequenceDetState() 3311 Returns the state of the sequence detection option for the context. 3312 When issued before context establishment completes or when the 3313 isProtReady method returns "false", it returns the desired state, 3314 otherwise it will indicate the actual state over the established 3315 context. 3317 7.4.36. getAnonymityState 3319 public boolean getAnonymityState() 3321 Returns "true" if this is an anonymous context. When issued before 3322 context establishment completes or when the isProtReady method 3323 returns "false", it returns the desired state, otherwise it will 3324 indicate the actual state over the established context. 3326 7.4.37. isTransferable 3328 public boolean isTransferable() throws GSSException 3330 Returns "true" if the context is transferable to other processes 3331 through the use of the export method. This call is only valid on 3332 fully established contexts. 3334 7.4.38. isProtReady 3336 public boolean isProtReady() 3338 Returns "true" if the per message operations can be applied over the 3339 context. Some mechanisms may allow the usage of per-message 3340 operations before the context is fully established. This will also 3341 indicate that the get methods will return actual context state 3342 characteristics instead of the desired ones. 3344 7.4.39. getConfState 3346 public boolean getConfState() 3348 Returns the confidentiality service state over the context. When 3349 issued before context establishment completes or when the isProtReady 3350 method returns "false", it returns the desired state, otherwise it 3351 will indicate the actual state over the established context. 3353 7.4.40. getIntegState 3355 public boolean getIntegState() 3357 Returns the integrity service state over the context. When issued 3358 before context establishment completes or when the isProtReady method 3359 returns "false", it returns the desired state, otherwise it will 3360 indicate the actual state over the established context. 3362 7.4.41. getLifetime 3364 public int getLifetime() 3366 Returns the context lifetime in seconds. When issued before context 3367 establishment completes or when the isProtReady method returns 3368 "false", it returns the desired lifetime, otherwise it will indicate 3369 the remaining lifetime for the context. 3371 7.4.42. getSrcName 3373 public GSSName getSrcName() throws GSSException 3375 Returns the name of the context initiator. This call is valid only 3376 after the context is fully established or the isProtReady method 3377 returns "true". It is guaranteed to return an MN. 3379 7.4.43. getTargName 3381 public GSSName getTargName() throws GSSException 3383 Returns the name of the context target (acceptor). This call is 3384 valid only after the context is fully established or the isProtReady 3385 method returns "true". It is guaranteed to return an MN. 3387 7.4.44. getMech 3389 public Oid getMech() throws GSSException 3391 Returns the mechanism oid for this context. This method may be 3392 called before the context is fully established, but the mechanism 3393 returned may change on successive calls in negotiated mechanism case. 3395 7.4.45. getDelegCred 3397 public GSSCredential getDelegCred() throws GSSException 3399 Returns the delegated credential object on the acceptor's side. To 3400 check for availability of delegated credentials call 3401 getDelegCredState. This call is only valid on fully established 3402 contexts. 3404 7.4.46. isInitiator 3406 public boolean isInitiator() throws GSSException 3408 Returns "true" if this is the initiator of the context. This call is 3409 only valid after the context creation process has started. 3411 7.5. public class MessageProp 3413 This is a utility class used within the per-message GSSContext 3414 methods to convey per-message properties. 3416 When used with the GSSContext interface's wrap and getMIC methods, an 3417 instance of this class is used to indicate the desired QOP and to 3418 request if confidentiality services are to be applied to caller 3419 supplied data (wrap only). To request default QOP, the value of 0 3420 should be used for QOP. 3422 When used with the unwrap and verifyMIC methods of the GSSContext 3423 interface, an instance of this class will be used to indicate the 3424 applied QOP and confidentiality services over the supplied message. 3425 In the case of verifyMIC, the confidentiality state will always be 3426 "false". Upon return from these methods, this object will also 3427 contain any supplementary status values applicable to the processed 3428 token. The supplementary status values can indicate old tokens, out 3429 of sequence tokens, gap tokens or duplicate tokens. 3431 7.5.1. Constructors 3433 public MessageProp(boolean privState) 3435 Constructor which sets QOP to 0 indicating that the default QOP is 3436 requested. 3438 Parameters: 3440 privState The desired privacy state. "true" for privacy and 3441 "false" for integrity only. 3443 public MessageProp(int qop, boolean privState) 3445 Constructor which sets the values for the qop and privacy state. 3447 Parameters: 3449 qop The desired QOP. Use 0 to request a default QOP. 3451 privState The desired privacy state. "true" for privacy and 3452 "false" for integrity only. 3454 7.5.2. getQOP 3456 public int getQOP() 3458 Retrieves the QOP value. 3460 7.5.3. getPrivacy 3462 public boolean getPrivacy() 3464 Retrieves the privacy state. 3466 7.5.4. getMinorStatus 3468 public int getMinorStatus() 3470 Retrieves the minor status that the underlying mechanism might have 3471 set. 3473 7.5.5. getMinorString 3475 public String getMinorString() 3477 Returns a string explaining the mechanism specific error code. null 3478 will be returned when no mechanism error code has been set. 3480 7.5.6. setQOP 3482 public void setQOP(int qopVal) 3484 Sets the QOP value. 3486 Parameters: 3488 qopVal The QOP value to be set. Use 0 to request a default QOP 3489 value. 3491 7.5.7. setPrivacy 3493 public void setPrivacy(boolean privState) 3495 Sets the privacy state. 3497 Parameters: 3499 privState The privacy state to set. 3501 7.5.8. isDuplicateToken 3503 public boolean isDuplicateToken() 3505 Returns "true" if this is a duplicate of an earlier token. 3507 7.5.9. isOldToken 3509 public boolean isOldToken() 3511 Returns "true" if the token's validity period has expired. 3513 7.5.10. isUnseqToken 3515 public boolean isUnseqToken() 3517 Returns "true" if a later token has already been processed. 3519 7.5.11. isGapToken 3521 public boolean isGapToken() 3523 Returns "true" if an expected per-message token was not received. 3525 7.5.12. setSupplementaryStates 3527 public void setSupplementaryStates(boolean duplicate, 3528 boolean old, boolean unseq, boolean gap, 3529 int minorStatus, String minorString) 3531 This method sets the state for the supplementary information flags 3532 and the minor status in MessageProp. It is not used by the 3533 application but by the GSS implementation to return this information 3534 to the caller of a per-message context method. 3536 Parameters: 3538 duplicate true if the token was a duplicate of an earlier token, 3539 false otherwise 3541 old true if the token's validity period has expired, false 3542 otherwise 3544 unseq true if a later token has already been processed, false 3545 otherwise 3547 gap true if one or more predecessor tokens have not yet been 3548 successfully processed, false otherwise 3550 minorStatus the integer minor status code that the underlying 3551 mechanism wants to set 3553 minorString the textual representation of the minorStatus value 3555 7.6. public class ChannelBinding 3557 The GSS-API accommodates the concept of caller-provided channel 3558 binding information. Channel bindings are used to strengthen the 3559 quality with which peer entity authentication is provided during 3560 context establishment. They enable the GSS-API callers to bind the 3561 establishment of the security context to relevant characteristics 3562 like addresses or to application specific data. 3564 The caller initiating the security context must determine the 3565 appropriate channel binding values to set in the GSSContext object. 3566 The acceptor must provide an identical binding in order to validate 3567 that received tokens possess correct channel-related characteristics. 3569 Use of channel bindings is optional in GSS-API. Since channel- 3570 binding information may be transmitted in context establishment 3571 tokens, applications should therefore not use confidential data as 3572 channel-binding components. 3574 7.6.1. Constructors 3576 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3577 byte[] appData) 3579 Create a ChannelBinding object with user supplied address information 3580 and data. "null" values can be used for any fields which the 3581 application does not want to specify. 3583 Parameters: 3585 initAddr The address of the context initiator. "null" value can be 3586 supplied to indicate that the application does not want to set 3587 this value. 3589 acceptAddr The address of the context acceptor. "null" value can 3590 be supplied to indicate that the application does not want to set 3591 this value. 3593 appData Application supplied data to be used as part of the 3594 channel bindings. "null" value can be supplied to indicate that 3595 the application does not want to set this value. 3597 public ChannelBinding(byte[] appData) 3599 Creates a ChannelBinding object without any addressing information. 3601 Parameters: 3603 appData Application supplied data to be used as part of the 3604 channel bindings. 3606 7.6.2. getInitiatorAddress 3608 public InetAddress getInitiatorAddress() 3610 Returns the initiator's address for this channel binding. "null" is 3611 returned if the address has not been set. 3613 7.6.3. getAcceptorAddress 3615 public InetAddress getAcceptorAddress() 3617 Returns the acceptor's address for this channel binding. "null" is 3618 returned if the address has not been set. 3620 7.6.4. getApplicationData 3622 public byte[] getApplicationData() 3624 Returns application data being used as part of the ChannelBinding. 3625 "null" is returned if no application data has been specified for the 3626 channel binding. 3628 7.6.5. equals 3630 public boolean equals(Object obj) 3632 Returns "true" if two channel bindings match. (Note that the Java 3633 language specification requires that two objects that are equal 3634 according to the equals(Object) method must return the same integer 3635 result when the hashCode() method is called on them.) 3637 Parameters: 3639 obj Another channel binding to compare with. 3641 7.7. public class Oid 3643 This class represents Universal Object Identifiers (Oids) and their 3644 associated operations. 3646 Oids are hierarchically globally-interpretable identifiers used 3647 within the GSS-API framework to identify mechanisms and name formats. 3649 The structure and encoding of Oids is defined in ISOIEC-8824 and 3650 ISOIEC-8825. For example the Oid representation of Kerberos V5 3651 mechanism is "1.2.840.113554.1.2.2" 3653 The GSSName name class contains public static Oid objects 3654 representing the standard name types defined in GSS-API. 3656 7.7.1. Constructors 3658 public Oid(String strOid) throws GSSException 3660 Creates an Oid object from a string representation of its integer 3661 components (e.g. "1.2.840.113554.1.2.2"). 3663 Parameters: 3665 strOid The string representation for the oid. 3667 public Oid(InputStream derOid) throws GSSException 3669 Creates an Oid object from its DER encoding. This refers to the full 3670 encoding including tag and length. The structure and encoding of 3671 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3672 identical in functionality to its byte array counterpart. 3674 Parameters: 3676 derOid Stream containing the DER encoded oid. 3678 public Oid(byte[] DEROid) throws GSSException 3680 Creates an Oid object from its DER encoding. This refers to the full 3681 encoding including tag and length. The structure and encoding of 3682 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3683 identical in functionality to its byte array counterpart. 3685 Parameters: 3687 derOid Byte array storing a DER encoded oid. 3689 7.7.2. toString 3691 public String toString() 3693 Returns a string representation of the oid's integer components in 3694 dot separated notation (e.g. "1.2.840.113554.1.2.2"). 3696 7.7.3. equals 3698 public boolean equals(Object Obj) 3700 Returns "true" if the two Oid objects represent the same oid value. 3701 (Note that the Java language specification [JLS] requires that two 3702 objects that are equal according to the equals(Object) method must 3703 return the same integer result when the hashCode() method is called 3704 on them.) 3706 Parameters: 3708 obj Another Oid object to compare with. 3710 7.7.4. getDER 3712 public byte[] getDER() 3714 Returns the full ASN.1 DER encoding for this oid object, which 3715 includes the tag and length. 3717 7.7.5. containedIn 3719 public boolean containedIn(Oid[] oids) 3721 A utility method to test if an Oid object is contained within the 3722 supplied Oid object array. 3724 Parameters: 3726 oids An array of oids to search. 3728 7.8. public class GSSException extends Exception 3730 This exception is thrown whenever a fatal GSS-API error occurs 3731 including mechanism specific errors. It may contain both, the major 3732 and minor, GSS-API status codes. The mechanism implementers are 3733 responsible for setting appropriate minor status codes when throwing 3734 this exception. Aside from delivering the numeric error code(s) to 3735 the caller, this class performs the mapping from their numeric values 3736 to textual representations. All Java GSS-API methods are declared 3737 throwing this exception. 3739 All implementations are encouraged to use the Java 3740 internationalization techniques to provide local translations of the 3741 message strings. 3743 7.8.1. Static Constants 3745 All valid major GSS-API error code values are declared as constants 3746 in this class. 3748 public static final int BAD_BINDINGS 3750 Channel bindings mismatch error. The value of this constant is 1. 3752 public static final int BAD_MECH 3754 Unsupported mechanism requested error. The value of this constant is 3755 2 3757 public static final int BAD_NAME 3759 Invalid name provided error. The value of this constant is 3. 3761 public static final int BAD_NAMETYPE 3763 Name of unsupported type provided error. The value of this constant 3764 is 4. 3766 public static final int BAD_STATUS 3768 Invalid status code error - this is the default status value. The 3769 value of this constant is 5. 3771 public static final int BAD_MIC 3773 Token had invalid integrity check error. The value of this constant 3774 is 6. 3776 public static final int CONTEXT_EXPIRED 3778 Specified security context expired error. The value of this constant 3779 is 7. 3781 public static final int CREDENTIALS_EXPIRED 3783 Expired credentials detected error. The value of this constant is 8. 3785 public static final int DEFECTIVE_CREDENTIAL 3787 Defective credential error. The value of this constant is 9. 3789 public static final int DEFECTIVE_TOKEN 3791 Defective token error. The value of this constant is 10. 3793 public static final int FAILURE 3795 General failure, unspecified at GSS-API level. The value of this 3796 constant is 11. 3798 public static final int NO_CONTEXT 3800 Invalid security context error. The value of this constant is 12. 3802 public static final int NO_CRED 3804 Invalid credentials error. The value of this constant is 13. 3806 public static final int BAD_QOP 3808 Unsupported QOP value error. The value of this constant is 14. 3810 public static final int UNAUTHORIZED 3812 Operation unauthorized error. The value of this constant is 15. 3814 public static final int UNAVAILABLE 3816 Operation unavailable error. The value of this constant is 16. 3818 public static final int DUPLICATE_ELEMENT 3820 Duplicate credential element requested error. The value of this 3821 constant is 17. 3823 public static final int NAME_NOT_MN 3825 Name contains multi-mechanism elements error. The value of this 3826 constant is 18. 3828 public static final int DUPLICATE_TOKEN 3830 The token was a duplicate of an earlier token. This is contained in 3831 an exception only when detected during context establishment, in 3832 which case it is considered a fatal error. (Non-fatal supplementary 3833 codes are indicated via the MessageProp object.) The value of this 3834 constant is 19. 3836 public static final int OLD_TOKEN 3838 The token's validity period has expired. This is contained in an 3839 exception only when detected during context establishment, in which 3840 case it is considered a fatal error. (Non-fatal supplementary codes 3841 are indicated via the MessageProp object.) The value of this 3842 constant is 20. 3844 public static final int UNSEQ_TOKEN 3846 A later token has already been processed. This is contained in an 3847 exception only when detected during context establishment, in which 3848 case it is considered a fatal error. (Non-fatal supplementary codes 3849 are indicated via the MessageProp object.) The value of this 3850 constant is 21. 3852 public static final int GAP_TOKEN 3854 An expected per-message token was not received. This is contained in 3855 an exception only when detected during context establishment, in 3856 which case it is considered a fatal error. (Non-fatal supplementary 3857 codes are indicated via the MessageProp object.) The value of this 3858 constant is 22. 3860 7.8.2. Constructors 3862 public GSSException(int majorCode) 3864 Creates a GSSException object with a specified major code. 3866 Parameters: 3868 majorCode The GSS error code causing this exception to be thrown. 3870 public GSSException(int majorCode, int minorCode, String minorString) 3872 Creates a GSSException object with the specified major code, minor 3873 code, and minor code textual explanation. This constructor is to be 3874 used when the exception is originating from the security mechanism. 3875 It allows to specify the GSS code and the mechanism code. 3877 Parameters: 3879 majorCode The GSS error code causing this exception to be thrown. 3881 minorCode The mechanism error code causing this exception to be 3882 thrown. 3884 minorString The textual explanation of the mechanism error code. 3886 7.8.3. getMajor 3888 public int getMajor() 3890 Returns the major code representing the GSS error code that caused 3891 this exception to be thrown. 3893 7.8.4. getMinor 3895 public int getMinor() 3897 Returns the mechanism error code that caused this exception. The 3898 minor code is set by the underlying mechanism. Value of 0 indicates 3899 that mechanism error code is not set. 3901 7.8.5. getMajorString 3903 public String getMajorString() 3905 Returns a string explaining the GSS major error code causing this 3906 exception to be thrown. 3908 7.8.6. getMinorString 3910 public String getMinorString() 3912 Returns a string explaining the mechanism specific error code. null 3913 will be returned when no mechanism error code has been set. 3915 7.8.7. setMinor 3917 public void setMinor(int minorCode, String message) 3919 Used internally by the GSS-API implementation and the underlying 3920 mechanisms to set the minor code and its textual representation. 3922 Parameters: 3924 minorCode The mechanism specific error code. 3926 message A textual explanation of the mechanism error code. 3928 7.8.8. toString 3929 public String toString() 3931 Returns a textual representation of both the major and minor status 3932 codes. 3934 7.8.9. getMessage 3936 public String getMessage() 3938 Returns a detailed message of this exception. Overrides 3939 Throwable.getMessage. It is customary in Java to use this method to 3940 obtain exception information. 3942 8. Sample Applications 3944 8.1. Simple GSS Context Initiator 3946 import org.ietf.jgss.*; 3948 /** 3949 * This is a partial sketch for a simple client program that acts 3950 * as a GSS context initiator. It illustrates how to use the Java 3951 * bindings for the GSS-API specified in 3952 * Generic Security Service API Version 2 : Java bindings 3953 * 3954 * 3955 * This code sketch assumes the existence of a GSS-API 3956 * implementation that supports the mechanism that it will need 3957 * and is present as a library package (org.ietf.jgss) either as 3958 * part of the standard JRE or in the CLASSPATH the application 3959 * specifies. 3960 */ 3962 public class SimpleClient { 3964 private String serviceName; // name of peer (ie. server) 3965 private GSSCredential clientCred = null; 3966 private GSSContext context = null; 3967 private Oid mech; // underlying mechanism to use 3969 private GSSManager mgr = GSSManager.getInstance(); 3971 ... 3972 ... 3974 private void clientActions() { 3975 initializeGSS(); 3976 establishContext(); 3977 doCommunication(); 3978 } 3980 /** 3981 * Acquire credentials for the client. 3982 */ 3983 private void initializeGSS() { 3985 try { 3987 clientCred = mgr.createCredential(null /*default princ*/, 3988 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 3989 mech /* mechanism to use */, 3990 GSSCredential.INITIATE_ONLY /* init context */); 3992 print("GSSCredential created for " + 3993 cred.getName().toString()); 3994 print("Credential lifetime (sec)=" + 3995 cred.getRemainingLifetime()); 3996 } catch (GSSException e) { 3997 print("GSS-API error in credential acquisition: " 3998 + e.getMessage()); 3999 ... 4000 ... 4001 } 4003 ... 4004 ... 4005 } 4007 /** 4008 * Does the security context establishment with the 4009 * server. 4010 */ 4011 private void establishContext() { 4013 byte[] inToken = new byte[0]; 4014 byte[] outToken = null; 4016 try { 4018 GSSName peer = mgr.createName(serviceName, 4019 GSSName.NT_HOSTBASED_SERVICE); 4020 context = mgr.createContext(peer, mech, gssCred, 4021 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 4023 // Will need to support confidentiality 4024 context.requestConf(true); 4026 while (!context.isEstablished()) { 4028 outToken = context.initSecContext(inToken, 0, 4029 inToken.length); 4031 if (outToken != null) 4032 writeGSSToken(outToken); 4034 if (!context.isEstablished()) 4035 inToken = readGSSToken(); 4036 } 4038 GSSName peer = context.getSrcName(); 4039 print("Security context established with " + peer + 4040 " using underlying mechanism " + mech.toString()); 4041 } catch (GSSException e) { 4042 print("GSS-API error during context establishment: " 4043 + e.getMessage()); 4044 ... 4045 ... 4046 } 4048 ... 4049 ... 4050 } 4052 /** 4053 * Sends some data to the server and reads back the 4054 * response. 4055 */ 4056 private void doCommunication() { 4057 byte[] inToken = null; 4058 byte[] outToken = null; 4059 byte[] buffer; 4061 // Container for multiple input-output arguments to and 4062 // from the per-message routines (e.g., wrap/unwrap). 4063 MessageProp messgInfo = new MessageProp(); 4065 try { 4067 /* 4068 * Now send some bytes to the server to be 4069 * processed. They will be integrity protected but 4070 * not encrypted for privacy. 4071 */ 4073 buffer = readFromFile(); 4075 // Set privacy to false and use the default QOP 4076 messgInfo.setPrivacy(false); 4078 outToken = context.wrap(buffer, 0, buffer.length, 4079 messgInfo); 4081 writeGSSToken(outToken); 4083 /* 4084 * Now read the response from the server. 4085 */ 4087 inToken = readGSSToken(); 4088 buffer = context.unwrap(inToken, 0, 4089 inToken.length, messgInfo); 4090 // All ok if no exception was thrown! 4092 GSSName peer = context.getSrcName(); 4094 print("Message from " + peer.toString() 4095 + " arrived."); 4096 print("Was it encrypted? " + 4097 messgInfo.getPrivacy()); 4098 print("Duplicate Token? " + 4099 messgInfo.isDuplicateToken()); 4100 print("Old Token? " + 4101 messgInfo.isOldToken()); 4102 print("Unsequenced Token? " + 4103 messgInfo.isUnseqToken()); 4104 print("Gap Token? " + 4105 messgInfo.isGapToken()); 4107 ... 4108 ... 4110 } catch (GSSException e) { 4111 print("GSS-API error in per-message calls: " 4112 + e.getMessage()); 4113 ... 4114 ... 4116 } 4118 ... 4120 ... 4122 } // end of doCommunication method 4124 ... 4125 ... 4127 } // end of class SimpleClient 4129 8.2. Simple GSS Context Acceptor 4131 import org.ietf.jgss.*; 4133 /** 4134 * This is a partial sketch for a simple server program that acts 4135 * as a GSS context acceptor. It illustrates how to use the Java 4136 * bindings for the GSS-API specified in 4137 * Generic Security Service API Version 2 : Java bindings 4138 * 4139 * This code sketch assumes the existence of a GSS-API 4140 * implementation that supports the mechanisms that it will need 4141 * and is present as a library package (org.ietf.jgss) either as 4142 * part of the standard JRE or in the CLASSPATH the application 4143 * specifies. 4144 */ 4146 import org.ietf.jgss.*; 4148 public class SimpleServer { 4150 private String serviceName; 4151 private GSSName name; 4152 private GSSCredential cred; 4154 private GSSManager mgr; 4156 ... 4157 ... 4159 /** 4160 * Wait for client connections, establish security contexts 4161 * and provide service. 4162 */ 4163 private void loop() { 4165 ... 4166 ... 4168 mgr = GSSManager.getInstance(); 4169 name = mgr.createName(serviceName, 4170 GSSName.NT_HOSTBASED_SERVICE); 4172 cred = mgr.createCredential(name, 4173 GSSCredential.INDEFINITE_LIFETIME, 4174 null, 4175 GSSCredential.ACCEPT_ONLY); 4177 // Loop infinitely 4178 while (true) { 4180 Socket s = serverSock.accept(); 4182 // Start a new thread to serve this connection 4183 Thread serverThread = new ServerThread(s); 4184 serverThread.start(); 4186 } 4187 } 4189 /** 4190 * Inner class ServerThread whose run() method provides the 4191 * secure service to a connection. 4192 */ 4194 private class ServerThread extends Thread { 4196 ... 4197 ... 4199 /** 4200 * Deals with the connection from one client. It also 4201 * handles all GSSException's thrown while talking to 4202 * this client. 4203 */ 4204 public void run() { 4206 byte[] inToken = null; 4207 byte[] outToken = null; 4208 byte[] buffer; 4210 GSSName peer; 4212 // Container for multiple input-output arguments to 4213 // and from the per-message routines 4214 // (i.e. wrap/unwrap). 4215 MessageProp supplInfo = new MessageProp(); 4216 GSSContext secContext = null; 4218 try { 4220 // Now do the context establishment loop 4222 GSSContext context = mgr.createContext(cred); 4224 while (!context.isEstablished()) { 4226 inToken = readGSSToken(); 4228 outToken = context.acceptSecContext(inToken, 4229 0, inToken.length); 4231 if (outToken != null) 4232 writeGSSToken(outToken); 4234 } 4236 // SimpleServer wants confidentiality to be 4237 // available. Check for it. 4238 if (!context.getConfState()){ 4239 ... 4240 ... 4241 } 4243 GSSName peer = context.getSrcName(); 4244 Oid mech = context.getMech(); 4245 print("Security context established with " + 4246 peer.toString() + 4247 " using underlying mechanism " + 4248 mech.toString() + 4249 " from Provider " + 4250 context.getProvider().getName()); 4252 // Now read the bytes sent by the client to be 4253 // processed. 4254 inToken = readGSSToken(); 4256 // Unwrap the message 4257 buffer = context.unwrap(inToken, 0, 4258 inToken.length, supplInfo); 4259 // All ok if no exception was thrown! 4261 // Print other supplementary per-message status 4262 // information 4264 print("Message from " + 4265 peer.toString() + " arrived."); 4266 print("Was it encrypted? " + 4267 supplInfo.getPrivacy()); 4268 print("Duplicate Token? " + 4269 supplInfo.isDuplicateToken()); 4270 print("Old Token? " + supplInfo.isOldToken()); 4271 print("Unsequenced Token? " + 4272 supplInfo.isUnseqToken()); 4273 print("Gap Token? " + supplInfo.isGapToken()); 4275 /* 4276 * Now process the bytes and send back an 4277 * encrypted response. 4278 */ 4280 buffer = serverProcess(buffer); 4282 // Encipher it and send it across 4284 supplInfo.setPrivacy(true); // privacy requested 4285 supplInfo.setQOP(0); // default QOP 4286 outToken = context.wrap(buffer, 0, buffer.length, 4287 supplInfo); 4288 writeGSSToken(outToken); 4290 } catch (GSSException e) { 4291 print("GSS-API Error: " + e.getMessage()); 4292 // Alternatively, could call e.getMajorMessage() 4293 // and e.getMinorMessage() 4294 print("Abandoning security context."); 4296 ... 4297 ... 4299 } 4301 ... 4302 ... 4304 } // end of run method in ServerThread 4306 } // end of inner class ServerThread 4308 ... 4309 ... 4311 } // end of class SimpleServer 4313 9. Security Considerations 4315 The Java language security model allows platform providers to have 4316 policy based fine-grained access control over any resource that an 4317 application wants. When using a Java security manager (such as, but 4318 not limited to, the case of applets running in browsers) the 4319 application code is in a sandbox by default. 4321 Administrators of the platform JRE determine what permissions, if 4322 any, are to be given to source from different codebases. Thus the 4323 administrator has to be aware of any special requirements that the 4324 GSS provider might have for system resources. For instance, a 4325 Kerberos provider might wish to make a network connection to the KDC 4326 to obtain initial credentials. This would not be allowed under the 4327 sandbox unless the administrator had granted permissions for this. 4328 Also note that this granting and checking of permissions happens 4329 transparently to the application and is outside the scope of this 4330 document. 4332 The Java language allows administrators to pre-configure a list of 4333 security service providers in the /lib/security/java.security 4334 file. At runtime, the system approaches these providers in order of 4335 preference when looking for security related services. Applications 4336 have a means to modify this list through methods in the "Security" 4337 class in the "java.security" package. However, since these 4338 modifications would be visible in the entire JVM and thus affect all 4339 code executing in it, this operation is not available in the sandbox 4340 and requires special permissions to perform. Thus when a GSS 4341 application has special needs that are met by a particular security 4342 provider, it has two choices: 4344 1) To install the provider on a JVM wide basis using the 4345 java.security.Security class and then depend on the system to find 4346 the right provider automatically when the need arises. (This would 4347 require the application to be granted a "insertProvider 4348 SecurityPermission".) 4350 2) To pass an instance of the provider to the local instance of 4351 GSSManager so that only factory calls going through that GSSManager 4352 use the desired provider. (This would not require any permissions.) 4354 10. IANA Considerations 4356 This document has no IANA considerations currently. 4358 11. Acknowledgments 4360 This proposed API leverages earlier work performed by the IETF's CAT 4361 WG as outlined in both RFC 2743 [GSSAPIv2-UPDATE] and RFC 2744 4362 [GSSAPI-Cbind]. Many conceptual definitions, implementation 4363 directions, and explanations have been included from these documents. 4365 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4366 Saltz and other members of Sun's development team for their helpful 4367 input, comments and suggestions. 4369 We would also like to thank Joe Salowey, and Michael Smith for many 4370 insightful ideas and suggestions that have contributed to this 4371 document. 4373 Appendix A. Changes since RFC 2853 4375 This document has following changes: 4377 1) Major GSS Status Code Constant Values 4379 RFC 2853 listed all the GSS status code values in two different 4380 sections: section 4.12.1 defined numeric values for them, and section 4381 6.8.1 defined them as static constants in the GSSException class 4382 without assigning any values. Due to an inconsistent ordering 4383 between these two sections, all of the GSS major status codes 4384 resulted in misalignment, and a subsequent disagreement between 4385 deployed implementations. 4387 This document defines the numeric values of the GSS status codes in 4388 both sections, while maintaining the original ordering from section 4389 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status code values 4390 defined in 4.12.1. The relevant sections in this document are 4391 sections 5.12.1 and 7.8.1. 4393 2) GSS Credential Usage Constant Values 4395 RFC 2853 section 6.3.2 defines static constants for the GSSCredential 4396 usage flags. However, the values of these constants were not defined 4397 anywhere in RFC 2853 [RFC2853]. 4399 This document defines the credential usage values in section 7.3.2. 4400 The original ordering of these values from section 6.3.2 of RFC 2853 4401 [RFC2853] is maintained. 4403 3) GSS Host-Based Service Name 4404 RFC 2853 [RFC2853] section 6.2.2 defines the static constant for the 4405 GSS host-based service OID NT_HOSTBASED_SERVICE, using a deprecated 4406 OID value. 4408 This document updates the NT_HOSTBASED_SERVICE OID value in section 4409 7.2.2 to be consistent with the C-bindings in RFC 2744 4410 [GSSAPI-Cbind]. 4412 12. References 4414 12.1. Normative References 4416 [GSSAPI-Cbind] 4417 Wray, J., "Generic Security Service API Version 2 : 4418 C-bindings", RFC 2744, January 2000. 4420 [GSSAPIv2-UPDATE] 4421 Linn, J., "Generic Security Service Application Program 4422 Interface, Version 2, Update 1", RFC 2743, January 2000. 4424 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism", 4425 RFC 2025, October 1996. 4427 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4428 Requirement Levels", BCP 14, RFC 2119, March 1997. 4430 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service 4431 Application Program Interface : Java Bindings", RFC 2853, 4432 June 2000. 4434 [RFC4121] Zhu, L. and S. Hartman, "The Kerberos Version 5 Generic 4435 Security Service Application Program Interface (GSS-API) 4436 Mechanism: Version 2", RFC 4121, July 2005. 4438 12.2. Informative References 4440 [JLS] Gosling, J., "The Java Language Specification", 4441 JLS langspec. 4443 Authors' Addresses 4445 Mayank D. Upadhyay 4446 Google Inc. 4447 1600 Amphitheatre Parkway 4448 Mountain View, CA 94043 4449 USA 4450 Email: mayank+ietf-2853@google.com 4452 Seema Malkani 4453 Sun Microsystems, Inc. 4454 4140 Network Circle 4455 Santa Clara, CA 95054 4456 USA 4458 Email: Seema.Malkani@sun.com 4460 Full Copyright Statement 4462 Copyright (C) The IETF Trust (2007). 4464 This document is subject to the rights, licenses and restrictions 4465 contained in BCP 78, and except as set forth therein, the authors 4466 retain all their rights. 4468 This document and the information contained herein are provided on an 4469 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4470 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4471 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4472 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4473 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4474 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4476 Intellectual Property 4478 The IETF takes no position regarding the validity or scope of any 4479 Intellectual Property Rights or other rights that might be claimed to 4480 pertain to the implementation or use of the technology described in 4481 this document or the extent to which any license under such rights 4482 might or might not be available; nor does it represent that it has 4483 made any independent effort to identify any such rights. Information 4484 on the procedures with respect to rights in RFC documents can be 4485 found in BCP 78 and BCP 79. 4487 Copies of IPR disclosures made to the IETF Secretariat and any 4488 assurances of licenses to be made available, or the result of an 4489 attempt made to obtain a general license or permission for the use of 4490 such proprietary rights by implementers or users of this 4491 specification can be obtained from the IETF on-line IPR repository at 4492 http://www.ietf.org/ipr. 4494 The IETF invites any interested party to bring to its attention any 4495 copyrights, patents or patent applications, or other proprietary 4496 rights that may cover technology that may be required to implement 4497 this standard. Please address the information to the IETF at 4498 ietf-ipr@ietf.org. 4500 Acknowledgment 4502 Funding for the RFC Editor function is provided by the IETF 4503 Administrative Support Activity (IASA).