idnits 2.17.1 draft-ietf-cat-gssv2-javabind-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == It seems as if not all pages are separated by form feeds - found 0 form feeds but 99 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The abstract seems to contain references ([SPKM], [GSSAPIv2], [KERBV5]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 307 has weird spacing: '...ment of a sec...' == Line 386 has weird spacing: '...rmation to en...' == Line 1250 has weird spacing: '...ith the major...' == Line 3183 has weird spacing: '...nStream inStr...' == Line 3717 has weird spacing: '...rStatus the ...' == (2 more instances...) -- 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 (December 1999) is 8891 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) -- Missing reference section? 'GSSAPIv2' on line 4608 looks like a reference -- Missing reference section? 'SPKM' on line 4625 looks like a reference -- Missing reference section? 'KERBV5' on line 44 looks like a reference -- Missing reference section? 'GSSAPI-C' on line 247 looks like a reference -- Missing reference section? '0' on line 4230 looks like a reference -- Missing reference section? 'GSSAPIv2-UPDATE' on line 4612 looks like a reference -- Missing reference section? 'GSSAPI-Cbind' on line 4617 looks like a reference Summary: 4 errors (**), 0 flaws (~~), 10 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Internet-Draft Jack Kabat 2 IETF CAT Working Group ValiCert, Inc. 3 Document: Mayank Upadhyay 4 Sun Microsystems, Inc. 6 December 1999 8 Generic Security Service API Version 2 : Java bindings 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet- Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 Abstract 33 The Generic Security Services Application Program Interface (GSS-API) 34 offers application programmers uniform access to security services 35 atop a variety of underlying cryptographic mechanisms. This document 36 specifies the Java bindings for GSS-API which is described at a 37 language independent conceptual level in RFC 2078 [GSSAPIv2]. 39 The GSS-API allows a caller application to authenticate a principal 40 identity, to delegate rights to a peer, and to apply security 41 services such as confidentiality and integrity on a per-message 42 basis. Examples of security mechanisms defined for GSS-API are The 43 Simple Public-Key GSS-API Mechanism [SPKM] and The Kerberos Version 5 44 GSS-API Mechanism [KERBV5]. 46 GSS-API Java Bindings December 1999 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 51 2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 7 52 3. Additional Controls . . . . . . . . . . . . . . . . . . . . 8 53 3.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . . 9 54 3.2. Mutual Authentication . . . . . . . . . . . . . . . . . 10 55 3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 11 56 3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 11 57 3.5. Confidentiality . . . . . . . . . . . . . . . . . . . . 12 58 3.6. Inter-process Context Transfer . . . . . . . . . . . . . 13 59 3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 13 60 4. Calling Conventions . . . . . . . . . . . . . . . . . . . 14 61 4.1. Package Name . . . . . . . . . . . . . . . . . . . . . . 14 62 4.2. Provider Framework . . . . . . . . . . . . . . . . . . . 14 63 4.3. Integer types . . . . . . . . . . . . . . . . . . . . . 15 64 4.4. Opaque Data types . . . . . . . . . . . . . . . . . . . 15 65 4.5. Strings . . . . . . . . . . . . . . . . . . . . . . . . 15 66 4.6. Object Identifiers . . . . . . . . . . . . . . . . . . . 16 67 4.7. Object Identifier Sets . . . . . . . . . . . . . . . . . 16 68 4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . 16 69 4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18 70 4.10. Authentication tokens . . . . . . . . . . . . . . . . . 19 71 4.11. Interprocess tokens . . . . . . . . . . . . . . . . . . 19 72 4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . 20 73 4.12.1. GSS status codes . . . . . . . . . . . . . . . . . . 20 74 4.12.2. Mechanism-specific status codes . . . . . . . . . . . 22 75 4.12.3. Supplementary status codes . . . . . . . . . . . . . 22 76 4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . 23 77 4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . 26 78 4.15. Stream Objects . . . . . . . . . . . . . . . . . . . . 27 79 4.16. Optional Parameters . . . . . . . . . . . . . . . . . . 27 80 5. Introduction to GSS-API Classes and Interfaces . . . . . . 27 81 5.1. GSSManager class . . . . . . . . . . . . . . . . . . . . 28 82 5.2. GSSName interface . . . . . . . . . . . . . . . . . . . 28 83 5.3. GSSCredential interface . . . . . . . . . . . . . . . . 29 84 5.4. GSSContext interface . . . . . . . . . . . . . . . . . . 30 85 5.5. MessageProp class . . . . . . . . . . . . . . . . . . . 31 86 5.6. GSSException class . . . . . . . . . . . . . . . . . . . 31 87 5.7. Oid class . . . . . . . . . . . . . . . . . . . . . . . 32 88 5.8. ChannelBinding class . . . . . . . . . . . . . . . . . . 32 89 6. Detailed GSS-API Class Description . . . . . . . . . . . . 32 90 6.1. public abstract class GSSManager . . . . . . . . . . . . 32 91 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . . 34 92 6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 34 93 6.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . . 34 94 6.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 34 95 6.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 35 97 GSS-API Java Bindings December 1999 99 6.1.6. createName . . . . . . . . . . . . . . . . . . . . . . 35 100 6.1.7. createName . . . . . . . . . . . . . . . . . . . . . . 36 101 6.1.8. createName . . . . . . . . . . . . . . . . . . . . . . 36 102 6.1.9. createName . . . . . . . . . . . . . . . . . . . . . . 37 103 6.1.10. createCredential . . . . . . . . . . . . . . . . . . 37 104 6.1.11. createCredential . . . . . . . . . . . . . . . . . . 38 105 6.1.12. createCredential . . . . . . . . . . . . . . . . . . 38 106 6.1.13. createContext . . . . . . . . . . . . . . . . . . . . 39 107 6.1.14. createContext . . . . . . . . . . . . . . . . . . . . 39 108 6.1.15. createContext . . . . . . . . . . . . . . . . . . . . 40 109 6.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . 40 110 6.1.16.1. Example Code . . . . . . . . . . . . . . . . . . . 41 111 6.1.17. addProviderAtEnd . . . . . . . . . . . . . . . . . . 42 112 6.1.17.1. Example Code . . . . . . . . . . . . . . . . . . . 42 113 6.2. public interface GSSName . . . . . . . . . . . . . . . . 43 114 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . . 43 115 6.2.2. Static Constants . . . . . . . . . . . . . . . . . . . 44 116 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 45 117 6.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 45 118 6.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . . 46 119 6.2.6. export . . . . . . . . . . . . . . . . . . . . . . . . 46 120 6.2.7. toString . . . . . . . . . . . . . . . . . . . . . . . 46 121 6.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 47 122 6.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 47 123 6.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . 47 124 6.3. public interface GSSCredential implements Cloneable . . 47 125 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . . 48 126 6.3.2. Static Constants . . . . . . . . . . . . . . . . . . . 49 127 6.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 49 128 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 50 129 6.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 50 130 6.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . . 50 131 6.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . . 50 132 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . . 51 133 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . . 51 134 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 51 135 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 51 136 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 52 137 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 52 138 6.4. public interface GSSContext . . . . . . . . . . . . . . 53 139 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . . 54 140 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . . 56 141 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . . 56 142 6.4.3.1. Example Code . . . . . . . . . . . . . . . . . . . . 56 143 6.4.4. initSecContext . . . . . . . . . . . . . . . . . . . . 57 144 6.4.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 58 145 6.4.5. acceptSecContext . . . . . . . . . . . . . . . . . . . 59 146 6.4.5.1. Example Code . . . . . . . . . . . . . . . . . . . . 59 148 GSS-API Java Bindings December 1999 150 6.4.6. acceptSecContext . . . . . . . . . . . . . . . . . . . 60 151 6.4.6.1. Example Code . . . . . . . . . . . . . . . . . . . . 61 152 6.4.7. isEstablished . . . . . . . . . . . . . . . . . . . . 62 153 6.4.8. dispose . . . . . . . . . . . . . . . . . . . . . . . 62 154 6.4.9. getWrapSizeLimit . . . . . . . . . . . . . . . . . . . 62 155 6.4.10. wrap . . . . . . . . . . . . . . . . . . . . . . . . 63 156 6.4.11. wrap . . . . . . . . . . . . . . . . . . . . . . . . 64 157 6.4.12. unwrap . . . . . . . . . . . . . . . . . . . . . . . 65 158 6.4.13. unwrap . . . . . . . . . . . . . . . . . . . . . . . 65 159 6.4.14. getMIC . . . . . . . . . . . . . . . . . . . . . . . 66 160 6.4.15. getMIC . . . . . . . . . . . . . . . . . . . . . . . 67 161 6.4.16. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 67 162 6.4.17. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 68 163 6.4.18. export . . . . . . . . . . . . . . . . . . . . . . . 69 164 6.4.19. requestMutualAuth . . . . . . . . . . . . . . . . . . 70 165 6.4.20. requestReplayDet . . . . . . . . . . . . . . . . . . 70 166 6.4.21. requestSequenceDet . . . . . . . . . . . . . . . . . 70 167 6.4.22. requestCredDeleg . . . . . . . . . . . . . . . . . . 71 168 6.4.23. requestAnonymity . . . . . . . . . . . . . . . . . . 71 169 6.4.24. requestConf . . . . . . . . . . . . . . . . . . . . . 71 170 6.4.25. requestInteg . . . . . . . . . . . . . . . . . . . . 71 171 6.4.26. requestLifetime . . . . . . . . . . . . . . . . . . . 72 172 6.4.27. setChannelBinding . . . . . . . . . . . . . . . . . . 72 173 6.4.28. getCredDelegState . . . . . . . . . . . . . . . . . . 72 174 6.4.29. getMutualAuthState . . . . . . . . . . . . . . . . . 72 175 6.4.30. getReplayDetState . . . . . . . . . . . . . . . . . . 73 176 6.4.31. getSequenceDetState . . . . . . . . . . . . . . . . . 73 177 6.4.32. getAnonymityState . . . . . . . . . . . . . . . . . . 73 178 6.4.33. isTransferable . . . . . . . . . . . . . . . . . . . 73 179 6.4.34. isProtReady . . . . . . . . . . . . . . . . . . . . . 74 180 6.4.35. getConfState . . . . . . . . . . . . . . . . . . . . 74 181 6.4.36. getIntegState . . . . . . . . . . . . . . . . . . . . 74 182 6.4.37. getLifetime . . . . . . . . . . . . . . . . . . . . . 74 183 6.4.38. getSrcName . . . . . . . . . . . . . . . . . . . . . 74 184 6.4.39. getTargName . . . . . . . . . . . . . . . . . . . . . 75 185 6.4.40. getMech . . . . . . . . . . . . . . . . . . . . . . . 75 186 6.4.41. getDelegCred . . . . . . . . . . . . . . . . . . . . 75 187 6.4.42. isInitiator . . . . . . . . . . . . . . . . . . . . . 75 188 6.5. public class MessageProp . . . . . . . . . . . . . . . . 75 189 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . . 76 190 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . . 76 191 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . . 76 192 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . . 77 193 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . . 77 194 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . . 77 195 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . . 77 196 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . . 77 197 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . . 78 199 GSS-API Java Bindings December 1999 201 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 78 202 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 78 203 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 78 204 6.6. public class ChannelBinding . . . . . . . . . . . . . . 79 205 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . . 79 206 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 80 207 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . . 80 208 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . . 80 209 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 80 210 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 81 211 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . . 81 212 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . . 82 213 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 82 214 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . . 82 215 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 82 216 6.8. public class GSSException extends Exception . . . . . . 83 217 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . . 83 218 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . . 86 219 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . . 86 220 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . . 86 221 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . . 87 222 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . . 87 223 6.8.7. setMinor . . . . . . . . . . . . . . . . . . . . . . . 87 224 6.8.8. toString . . . . . . . . . . . . . . . . . . . . . . . 87 225 6.8.9. getMessage . . . . . . . . . . . . . . . . . . . . . . 87 226 7. Sample Applications . . . . . . . . . . . . . . . . . . . 88 227 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 88 228 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . 92 229 8. Security Considerations . . . . . . . . . . . . . . . . . 96 230 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 97 231 10. Bibliography . . . . . . . . . . . . . . . . . . . . . . 98 232 11. Author's Address . . . . . . . . . . . . . . . . . . . . 99 234 GSS-API Java Bindings December 1999 236 1. Introduction 238 This document specifies Java language bindings for the Generic 239 Security Services Application Programming Interface (GSS-API) Version 240 2. GSS-API Version 2 is described in a language independent format in 241 RFC 2078 [GSSAPIv2]. The GSS-API allows a caller application to 242 authenticate a principal identity, to delegate rights to a peer, and 243 to apply security services such as confidentiality and integrity on a 244 per-message basis. 246 This document leverages the work performed by the WG in the area of 247 RFC 2078 [GSSAPIv2] the C-bindings draft [GSSAPI-C]. Whenever 248 appropriate, text has been used from the C-bindings document to 249 explain generic concepts and provide direction to the implementors. 251 The design goals of this API have been to satisfy all the 252 functionality defined in RFC 2078 and to provide these services in an 253 object oriented method. The specification also aims to satisfy the 254 needs of both types of Java application developers, those who would 255 like access to a "system-wide" GSS-API implementation, as well as 256 those who would want to provide their own "custom" implementation. 258 A "system-wide" implementation is one that is available to all 259 applications in the form of a library package. It may be a standard 260 package in the Java runtime environment (JRE) being used or it may be 261 additionally installed and accessible to any application via the 262 CLASSPATH. 264 A "custom" implementation of the GSS-API, on the other hand, is one 265 that would, in most cases, be bundled with the application during 266 distribution. It is expected that such an implementation would be 267 meant to provide for some particular need of the application, such as 268 support for some specific mechanism. 270 The design of this API also aims to provide a flexible framework to 271 add and manage GSS-API mechanisms. GSS-API leverages the JCA provider 272 concept to support the plugability of mechanisms. Mechanisms can be 273 added on a "system-wide" basis, where all users of the framework will 274 have them available. The specification also allows for the addition 275 of mechanisms per-instance the GSS-API. 277 Lastly, this specification presents an API that will naturally fit 278 within the operation environment of the Java platform. Readers are 279 assumed to be familiar with both the GSS-API and the Java platform. 281 GSS-API Java Bindings December 1999 283 2. GSS-API Operational Paradigm 285 The Generic Security Service Application Programming Interface 286 [GSSAPIv2] defines a generic security API to calling applications. 287 It allows a communicating application to authenticate the user 288 associated with another application, to delegate rights to another 289 application, and to apply security services such as confidentiality 290 and integrity on a per-message basis. 292 There are four stages to using GSS-API: 294 1) The application acquires a set of credentials with which it 295 may prove its identity to other processes. The 296 application's credentials vouch for its global identity, 297 which may or may not be related to any local username under 298 which it may be running. 300 2) A pair of communicating applications establish a joint 301 security context using their credentials. The security 302 context encapsulates shared state information, which is 303 required in order that per-message security services may be 304 provided. Examples of state information that might be 305 shared between applications as part of a security context 306 are cryptographic keys, and message sequence numbers. As 307 part of the establishment of a security context, the 308 context initiator is authenticated to the responder, and 309 may require that the responder is authenticated back to the 310 initiator. The initiator may optionally give the responder 311 the right to initiate further security contexts, acting as 312 an agent or delegate of the initiator. This transfer of 313 rights is termed "delegation", and is achieved by creating 314 a set of credentials, similar to those used by the 315 initiating application, but which may be used by the 316 responder. 318 A GSSContext object is used to establish and maintain the 319 shared information that makes up the security context. 320 Certain GSSContext methods will generate a token, which 321 applications treat as cryptographically protected, opaque 322 data. The caller of such GSSContext method is responsible 323 for transferring the token to the peer application, 324 encapsulated if necessary in an application-to-application 325 protocol. On receipt of such a token, the peer application 326 should pass it to a corresponding GSSContext method which 327 will decode the token and extract the information, updating 328 the security context state information accordingly. 330 GSS-API Java Bindings December 1999 332 3) Per-message services are invoked on a GSSContext object to 333 apply either: 335 integrity and data origin authentication, or 337 confidentiality, integrity and data origin 338 authentication 340 to application data, which are treated by GSS-API as 341 arbitrary octet-strings. An application transmitting a 342 message that it wishes to protect will call the appropriate 343 GSSContext method (getMIC or wrap) to apply protection, and 344 send the resulting token to the receiving application. The 345 receiver will pass the received token (and, in the case of 346 data protected by getMIC, the accompanying message-data) to 347 the corresponding decoding method of the GSSContext 348 interface (verifyMIC or unwrap) to remove the protection 349 and validate the data. 351 4) At the completion of a communications session (which may 352 extend across several transport connections), each 353 application uses a GSSContext method to invalidate the 354 security context and release any system or cryptographic 355 resources held. Multiple contexts may also be used (either 356 successively or simultaneously) within a single 357 communications association, at the discretion of the 358 applications. 360 3. Additional Controls 362 This section discusses the optional services that a context initiator 363 may request of the GSS-API before the context establishment. Each of 364 these services is requested by calling the appropriate mutator method 365 in the GSSContext object before the first call to init is performed. 366 Only the context initiator can request context flags. 368 The optional services defined are: 370 Delegation 371 The (usually temporary) transfer of rights from initiator to 372 acceptor, enabling the acceptor to authenticate itself as an 373 agent of the initiator. 375 Mutual Authentication 376 In addition to the initiator authenticating its identity to the 378 GSS-API Java Bindings December 1999 380 context acceptor, the context acceptor should also authenticate 381 itself to the initiator. 383 Replay Detection 384 In addition to providing message integrity services, GSSContext 385 per-message operations of getMIC and wrap should include message 386 numbering information to enable verifyMIC and unwrap to detect 387 if a message has been duplicated. 389 Out-of-Sequence Detection 390 In addition to providing message integrity services, GSSContext 391 per-message operations (getMIC and wrap) should include message 392 sequencing information to enable verifyMIC and unwrap to detect 393 if a message has been received out of sequence. 395 Anonymous Authentication 396 The establishment of the security context should not reveal the 397 initiator's identity to the context acceptor. 399 Some mechanisms may not support all optional services, and some 400 mechanisms may only support some services in conjunction with others. 401 The GSSContext interface offers query methods to allow the 402 verification by the calling application of which services will be 403 available from the context when the establishment phase is complete. 404 In general, if the security mechanism is capable of providing a 405 requested service, it should do so even if additional services must 406 be enabled in order to provide the requested service. If the 407 mechanism is incapable of providing a requested service, it should 408 proceed without the service leaving the application to abort the 409 context establishment process if it considers the requested service 410 to be mandatory. 412 Some mechanisms may specify that support for some services is 413 optional, and that implementors of the mechanism need not provide it. 414 This is most commonly true of the confidentiality service, often 415 because of legal restrictions on the use of data-encryption, but may 416 apply to any of the services. Such mechanisms are required to send 417 at least one token from acceptor to initiator during context 418 establishment when the initiator indicates a desire to use such a 419 service, so that the initiating GSS-API can correctly indicate 420 whether the service is supported by the acceptor's GSS-API. 422 3.1. Delegation 424 The GSS-API allows delegation to be controlled by the initiating 425 application via the requestCredDeleg method before the first call to 426 init has been issued. Some mechanisms do not support delegation, and 428 GSS-API Java Bindings December 1999 430 for such mechanisms attempts by an application to enable delegation 431 are ignored. 433 The acceptor of a security context, for which the initiator enabled 434 delegation, can check if delegation was enabled by using the 435 getCredDelegState method of the GSSContext interface. In cases when 436 it is, the delegated credential object can be obtained by calling the 437 getDelegCred method. The obtained GSSCredential object may then be 438 used to initiate subsequent GSS-API security contexts as an agent or 439 delegate of the initiator. If the original initiator's identity is 440 "A" and the delegate's identity is "B", then, depending on the 441 underlying mechanism, the identity embodied by the delegated 442 credential may be either "A" or "B acting for A". 444 For many mechanisms that support delegation, a simple boolean does 445 not provide enough control. Examples of additional aspects of 446 delegation control that a mechanism might provide to an application 447 are duration of delegation, network addresses from which delegation 448 is valid, and constraints on the tasks that may be performed by a 449 delegate. Such controls are presently outside the scope of the GSS- 450 API. GSS-API implementations supporting mechanisms offering 451 additional controls should provide extension routines that allow 452 these controls to be exercised (perhaps by modifying the initiator's 453 GSS-API credential object prior to its use in establishing a 454 context). However, the simple delegation control provided by GSS-API 455 should always be able to over-ride other mechanism-specific 456 delegation controls. If the application instructs the GSSContext 457 object that delegation is not desired, then the implementation must 458 not permit delegation to occur. This is an exception to the general 459 rule that a mechanism may enable services even if they are not 460 requested - delegation may only be provided at the explicit request 461 of the application. 463 3.2. Mutual Authentication 465 Usually, a context acceptor will require that a context initiator 466 authenticate itself so that the acceptor may make an access-control 467 decision prior to performing a service for the initiator. In some 468 cases, the initiator may also request that the acceptor authenticate 469 itself. GSS-API allows the initiating application to request this 470 mutual authentication service by calling the requestMutualAuth method 471 of the GSSContext interface with a "true" parameter before making the 472 first call to init. The initiating application is informed as to 473 whether or not the context acceptor has authenticated itself. Note 474 that some mechanisms may not support mutual authentication, and other 475 mechanisms may always perform mutual authentication, whether or not 476 the initiating application requests it. In particular, mutual 478 GSS-API Java Bindings December 1999 480 authentication may be required by some mechanisms in order to support 481 replay or out-of-sequence message detection, and for such mechanisms 482 a request for either of these services will automatically enable 483 mutual authentication. 485 3.3. Replay and Out-of-Sequence Detection 487 The GSS-API may provide detection of mis-ordered messages once a 488 security context has been established. Protection may be applied to 489 messages by either application, by calling either getMIC or wrap 490 methods of the GSSContext interface, and verified by the peer 491 application by calling verifyMIC or unwrap for the peer's GSSContext 492 object. 494 The getMIC method calculates a cryptographic checksum of an 495 application message, and returns that checksum in a token. The 496 application should pass both the token and the message to the peer 497 application, which presents them to the verifyMIC method of the 498 peer's GSSContext object. 500 The wrap method calculates a cryptographic checksum of an application 501 message, and places both the checksum and the message inside a single 502 token. The application should pass the token to the peer 503 application, which presents it to the unwrap method of the peer's 504 GSSContext object to extract the message and verify the checksum. 506 Either pair of routines may be capable of detecting out-of-sequence 507 message delivery, or duplication of messages. Details of such mis- 508 ordered messages are indicated through supplementary query methods of 509 the MessageProp object that is filled in by each of these routines. 511 A mechanism need not maintain a list of all tokens that have been 512 processed in order to support these status codes. A typical 513 mechanism might retain information about only the most recent "N" 514 tokens processed, allowing it to distinguish duplicates and missing 515 tokens within the most recent "N" messages; the receipt of a token 516 older than the most recent "N" would result in the isOldToken method 517 of the instance of MessageProp to return "true". 519 3.4. Anonymous Authentication 521 In certain situations, an application may wish to initiate the 522 authentication process to authenticate a peer, without revealing its 523 own identity. As an example, consider an application providing 524 access to a database containing medical information, and offering 525 unrestricted access to the service. A client of such a service might 527 GSS-API Java Bindings December 1999 529 wish to authenticate the service (in order to establish trust in any 530 information retrieved from it), but might not wish the service to be 531 able to obtain the client's identity (perhaps due to privacy concerns 532 about the specific inquiries, or perhaps simply to avoid being placed 533 on mailing-lists). 535 In normal use of the GSS-API, the initiator's identity is made 536 available to the acceptor as a result of the context establishment 537 process. However, context initiators may request that their identity 538 not be revealed to the context acceptor. Many mechanisms do not 539 support anonymous authentication, and for such mechanisms the request 540 will not be honored. An authentication token will still be 541 generated, but the application is always informed if a requested 542 service is unavailable, and has the option to abort context 543 establishment if anonymity is valued above the other security 544 services that would require a context to be established. 546 In addition to informing the application that a context is 547 established anonymously (via the isAnonymous method of the GSSContext 548 class), the getSrcName method of the acceptor's GSSContext object 549 will, for such contexts, return a reserved internal-form name, 550 defined by the implementation. 552 The toString method for a GSSName object representing an anonymous 553 entity will return a printable name. The returned value will be 554 syntactically distinguishable from any valid principal name supported 555 by the implementation. The associated name-type object identifier 556 will be an oid representing the value of NT_ANONYMOUS. This name- 557 type oid will be defined as a public, static Oid object of the 558 GSSName class. The printable form of an anonymous name should be 559 chosen such that it implies anonymity, since this name may appear in, 560 for example, audit logs. For example, the string "" might 561 be a good choice, if no valid printable names supported by the 562 implementation can begin with "<" and end with ">". 564 When using the equal method of the GSSName interface, and one of the 565 operands is a GSSName instance representing an anonymous entity, the 566 method must return "false". 568 3.5. Confidentiality 570 If a GSSContext supports the confidentiality service, wrap method may 571 be used to encrypt application messages. Messages are selectively 572 encrypted, under the control of the setPrivacy method of the 573 MessageProp object used in the wrap method. 575 GSS-API Java Bindings December 1999 577 3.6. Inter-process Context Transfer 579 GSS-API V2 provides functionality which allows a security context to 580 be transferred between processes on a single machine. These are 581 implemented using the export method of GSSContext and a byte array 582 constructor of the same class. The most common use for such a 583 feature is a client-server design where the server is implemented as 584 a single process that accepts incoming security contexts, which then 585 launches child processes to deal with the data on these contexts. In 586 such a design, the child processes must have access to the security 587 context object created within the parent so that they can use per- 588 message protection services and delete the security context when the 589 communication session ends. 591 Since the security context data structure is expected to contain 592 sequencing information, it is impractical in general to share a 593 context between processes. Thus GSSContext interface provides an 594 export method that the process, which currently owns the context, can 595 call to declare that it has no intention to use the context 596 subsequently, and to create an inter-process token containing 597 information needed by the adopting process to successfully re-create 598 the context. After successful completion of export, the original 599 security context is made inaccessible to the calling process by GSS- 600 API and any further usage of this object will result in failures. 601 The originating process transfers the inter-process token to the 602 adopting process, which creates a new GSSContext object using the 603 byte array constructor. The properties of the context are equivalent 604 to that of the original context. 606 The inter-process token may contain sensitive data from the original 607 security context (including cryptographic keys). Applications using 608 inter-process tokens to transfer security contexts must take 609 appropriate steps to protect these tokens in transit. 611 Implementations are not required to support the inter-process 612 transfer of security contexts. Calling the isTransferable method of 613 the GSSContext interface will indicate if the context object is 614 transferable. 616 3.7. The Use of Incomplete Contexts 618 Some mechanisms may allow the per-message services to be used before 619 the context establishment process is complete. For example, a 620 mechanism may include sufficient information in its initial context- 621 level tokens for the context acceptor to immediately decode messages 622 protected with wrap or getMIC. For such a mechanism, the initiating 623 application need not wait until subsequent context-level tokens have 625 GSS-API Java Bindings December 1999 627 been sent and received before invoking the per-message protection 628 services. 630 An application can invoke the isProtReady method of the GSSContext 631 class to determine if the per-message services are available in 632 advance of complete context establishment. Applications wishing to 633 use per-message protection services on partially-established contexts 634 should query this method before attempting to invoke wrap or getMIC. 636 4. Calling Conventions 638 Java provides the implementors with not just a syntax for the 639 language, but also an operational environment. For example, memory 640 is automatically managed and does not require application 641 intervention. These language features have allowed for a simpler API 642 and have led to the elimination of certain GSS-API functions. 644 Moreover, the Java Cryptographic Architecture (JCA) defines a 645 provider model which allows an implementation independent access to 646 its security services. Using this model, applications can seamlessly 647 switch between different implementations and dynamically add new 648 services. The GSS-API specification leverages these concepts by the 649 usage of providers for the mechanism implementations. 651 4.1. Package Name 653 The classes and interfaces defined in this document reside in the 654 package called "org.ietf.jgss". Applications that wish to make use 655 of this API should import this package name as shows in section 7. 657 4.2. Provider Framework 659 The Java security API's use a provider architecture that allows 660 applications to be implementation independent and security API 661 implementations to be modular and extensible. The 662 java.security.Provider class is an abstract class that a vendor 663 extends. This class maps various properties that represent different 664 security services that are available to the names of the actual 665 vendor classes that implement those services. When requesting a 666 service, an application simply specifies the desired provider and the 667 API delegates the request to service classes available from that 668 provider. 670 GSS-API Java Bindings December 1999 672 Using the Java security provider model insulates applications from 673 implementation details of the services they wish to use. 674 Applications can switch between providers easily and new providers 675 can be added as needed, even at runtime. 677 The GSS-API may use providers to find components for specific 678 underlying security mechanisms. For instance, a particular provider 679 might contain components that will allow the GSS-API to support the 680 Kerberos v5 mechanism and another might contain components to support 681 the SPKM mechanism. By delegating mechanism specific functionality 682 to the components obtained from providers the GSS-API can be extended 683 to support an arbitrary list of mechanism. 685 How the GSS-API locates and queries these providers is beyond the 686 scope of this document and is being deferred to a Service Provider 687 Interface (SPI) specification. The availability of such a SPI 688 specification is not mandatory for the adoption of this API 689 specification nor is it mandatory to use providers in the 690 implementation of a GSS-API framework. However, by using the provider 691 framework together with an SPI specification one can create an 692 extensible and implementation independent GSS-API framework. 694 4.3. Integer types 696 All numeric values are declared as "int" primitive Java type. The 697 Java specification guarantees that this will be a 32 bit two's 698 complement signed number. 700 Throughout this API, the "boolean" primitive Java type is used 701 wherever a boolean value is required or returned. 703 4.4. Opaque Data types 705 Java byte arrays are used to represent opaque data types which are 706 consumed and produced by the GSS-API in the forms of tokens. Java 707 arrays contain a length field which enables the users to easily 708 determine their size. The language has automatic garbage collection 709 which alleviates the need by developers to release memory and 710 simplifies buffer ownership issues. 712 4.5. Strings 714 The String object will be used to represent all textual data. The 715 Java String object, transparently treats all characters as two-byte 716 Unicode characters which allows support for many locals. All 718 GSS-API Java Bindings December 1999 720 routines returning or accepting textual data will use the String 721 object. 723 4.6. Object Identifiers 725 An Oid object will be used to represent Universal Object Identifiers 726 (Oids). Oids are ISO-defined, hierarchically globally-interpretable 727 identifiers used within the GSS-API framework to identify security 728 mechanisms and name formats. The Oid object can be created from a 729 string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as 730 well as from its ASN.1 DER encoding. Methods are also provided to 731 test equality and provide the DER representation for the object. 733 An important feature of the Oid class is that its instances are 734 immutable - i.e. there are no methods defined that allow one to 735 change the contents of an Oid. This property allows one to treat 736 these objects as "statics" without the need to perform copies. 738 Certain routines allow the usage of a default oid. A "null" value 739 can be used in those cases. 741 4.7. Object Identifier Sets 743 The Java bindings represents object identifiers sets as arrays of Oid 744 objects. All Java arrays contain a length field which allows for 745 easy manipulation and reference. 747 In order to support the full functionality of RFC 2078, the Oid class 748 includes a method which checks for existence of an Oid object within 749 a specified array. This is equivalent in functionality to 750 gss_test_oid_set_member. The use of Java arrays and Java's automatic 751 garbage collection has eliminated the need for the following 752 routines: gss_create_empty_oid_set, gss_release_oid_set, and 753 gss_add_oid_set_member. Java GSS-API implementations will not 754 contain them. Java's automatic garbage collection and the immutable 755 property of the Oid object eliminates the complicated memory 756 management issues of the C counterpart. 758 When ever a default value for an Object Identifier Set is required, a 759 "null" value can be used. Please consult the detailed method 760 description for details. 762 4.8. Credentials 764 GSS-API credentials are represented by the GSSCredential interface. 766 GSS-API Java Bindings December 1999 768 The interface contains several constructs to allow for the creation 769 of most common credential objects for the initiator and the acceptor. 770 Comparisons are performed using the interface's "equals" method. The 771 following general description of GSS-API credentials is included from 772 the C-bindings specification: 774 GSS-API credentials can contain mechanism-specific principal 775 authentication data for multiple mechanisms. A GSS-API credential is 776 composed of a set of credential-elements, each of which is applicable 777 to a single mechanism. A credential may contain at most one 778 credential-element for each supported mechanism. A credential- 779 element identifies the data needed by a single mechanism to 780 authenticate a single principal, and conceptually contains two 781 credential-references that describe the actual mechanism-specific 782 authentication data, one to be used by GSS-API for initiating 783 contexts, and one to be used for accepting contexts. For mechanisms 784 that do not distinguish between acceptor and initiator credentials, 785 both references would point to the same underlying mechanism-specific 786 authentication data. 788 Credentials describe a set of mechanism-specific principals, and give 789 their holder the ability to act as any of those principals. All 790 principal identities asserted by a single GSS-API credential should 791 belong to the same entity, although enforcement of this property is 792 an implementation-specific matter. A single GSSCredential object 793 represents all the credential elements that have been acquired. 795 The creation's of an GSSContext object allows the value of "null" to 796 be specified as the GSSCredential input parameter. This will 797 indicate a desire by the application to act as a default principal. 798 While individual GSS-API implementations are free to determine such 799 default behavior as appropriate to the mechanism, the following 800 default behavior by these routines is recommended for portability: 802 For the initiator side of the context: 804 1) If there is only a single principal capable of initiating 805 security contexts for the chosen mechanism that the 806 application is authorized to act on behalf of, then that 807 principal shall be used, otherwise 809 2) If the platform maintains a concept of a default network- 810 identity for the chosen mechanism, and if the application 811 is authorized to act on behalf of that identity for the 812 purpose of initiating security contexts, then the principal 813 corresponding to that identity shall be used, otherwise 815 3) If the platform maintains a concept of a default local 817 GSS-API Java Bindings December 1999 819 identity, and provides a means to map local identities into 820 network-identities for the chosen mechanism, and if the 821 application is authorized to act on behalf of the network- 822 identity image of the default local identity for the 823 purpose of initiating security contexts using the chosen 824 mechanism, then the principal corresponding to that 825 identity shall be used, otherwise 827 4) A user-configurable default identity should be used. 829 and for the acceptor side of the context 831 1) If there is only a single authorized principal identity 832 capable of accepting security contexts for the chosen 833 mechanism, then that principal shall be used, otherwise 835 2) If the mechanism can determine the identity of the target 836 principal by examining the context-establishment token 837 processed during the accept method, and if the accepting 838 application is authorized to act as that principal for the 839 purpose of accepting security contexts using the chosen 840 mechanism, then that principal identity shall be used, 841 otherwise 843 3) If the mechanism supports context acceptance by any 844 principal, and if mutual authentication was not requested, 845 any principal that the application is authorized to accept 846 security contexts under using the chosen mechanism may be 847 used, otherwise 849 4) A user-configurable default identity shall be used. 851 The purpose of the above rules is to allow security contexts to be 852 established by both initiator and acceptor using the default behavior 853 whenever possible. Applications requesting default behavior are 854 likely to be more portable across mechanisms and implementations than 855 ones that instantiate an GSSCredential object representing a specific 856 identity. 858 4.9. Contexts 860 The GSSContext interface is used to represent one end of a GSS-API 861 security context, storing state information appropriate to that end 862 of the peer communication, including cryptographic state information. 864 GSS-API Java Bindings December 1999 866 The instantiation of the context object is done differently by the 867 initiator and the acceptor. After the context has been instantiated, 868 the initiator may choose to set various context options which will 869 determine the characteristics of the desired security context. When 870 all the application desired characteristics have been set, the 871 initiator will call the initSecContext method which will produce a 872 token for consumption by the peer's acceptSecContext method. It is 873 the responsibility of the application to deliver the authentication 874 token(s) between the peer applications for processing. Upon 875 completion of the context establishment phase, context attributes can 876 be retrieved, by both the initiator and acceptor, using the accessor 877 methods. These will reflect the actual attributes of the established 878 context. At this point the context can be used by the application to 879 apply cryptographic services to its data. 881 4.10. Authentication tokens 883 A token is a caller-opaque type that GSS-API uses to maintain 884 synchronization between each end of the GSS-API security context. 885 The token is a cryptographically protected octet-string, generated by 886 the underlying mechanism at one end of a GSS-API security context for 887 use by the peer mechanism at the other end. Encapsulation (if 888 required) within the application protocol and transfer of the token 889 are the responsibility of the peer applications. 891 Java GSS-API uses byte arrays to represent authentication tokens. 892 Overloaded methods exist which allow the caller to supply input and 893 output streams which will be used for the reading and writing of the 894 token data. 896 4.11. Interprocess tokens 898 Certain GSS-API routines are intended to transfer data between 899 processes in multi-process programs. These routines use a caller- 900 opaque octet-string, generated by the GSS-API in one process for use 901 by the GSS-API in another process. The calling application is 902 responsible for transferring such tokens between processes. Note 903 that, while GSS-API implementors are encouraged to avoid placing 904 sensitive information within interprocess tokens, or to 905 cryptographically protect them, many implementations will be unable 906 to avoid placing key material or other sensitive data within them. 907 It is the application's responsibility to ensure that interprocess 908 tokens are protected in transit, and transferred only to processes 909 that are trustworthy. An interprocess token is represented using a 910 byte array emitted from the export method of the GSSContext 911 interface. The receiver of the interprocess token would initialize 913 GSS-API Java Bindings December 1999 915 an GSSContext object with this token to create a new context. Once a 916 context has been exported, the GSSContext object is invalidated and 917 is no longer available. 919 4.12. Error Reporting 921 RFC 2078 defined the usage of major and minor status values for 922 signaling of GSS-API errors. The major code, also called GSS status 923 code, is used to signal errors at the GSS-API level independent of 924 the underlying mechanism(s). The minor status value or Mechanism 925 status code, is a mechanism defined error value indicating a 926 mechanism specific error code. 928 Java GSS-API uses exceptions implemented by the GSSException class to 929 signal both minor and major error values. Both, mechanism specific 930 errors and GSS-API level errors are signaled through instances of 931 this class. The usage of exceptions replaces the need for major and 932 minor codes to be used within the API calls. GSSException class also 933 contains methods to obtain textual representations for both the major 934 and minor values, which is equivalent to the functionality of 935 gss_display_status. 937 4.12.1. GSS status codes 939 GSS status codes indicate errors that are independent of the 940 underlying mechanism(s) used to provide the security service. The 941 errors that can be indicated via a GSS status code are generic API 942 routine errors (errors that are defined in the GSS-API 943 specification). These bindings take advantage of the Java exceptions 944 mechanism, thus eliminating the need for calling errors. 946 A GSS status code indicates a single fatal generic API error from the 947 routine that has thrown the GSSException. Using exceptions announces 948 that a fatal error has occurred during the execution of the method. 949 The GSS-API operational model also allows for the signaling of 950 supplementary status information from the per-message calls. These 951 need to be handled as return values since using exceptions is not 952 appropriate for informatory or warning-like information. The methods 953 that are capable of producing supplementary information are the two 954 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 955 These methods fill the supplementary status codes in the MessageProp 956 object that was passed in. 958 GSSException object, along with providing the functionality for 959 setting of the various error codes and translating them into textual 960 representation, also contains the definitions of all the numeric 962 GSS-API Java Bindings December 1999 964 error values. The following table lists the definitions of error 965 codes: 967 Table: GSS Status Codes 969 Name Value Meaning 971 BAD_MECH 1 An unsupported mechanism 972 was requested. 974 BAD_NAME 2 An invalid name was supplied. 976 BAD_NAMETYPE 3 A supplied name was of an 977 unsupported type. 979 BAD_BINDINGS 4 Incorrect channel bindings were 980 supplied. 982 BAD_STATUS 5 An invalid status code was 983 supplied. 985 BAD_MIC 6 A token had an invalid MIC. 987 NO_CRED 7 No credentials were supplied, or 988 the credentials were unavailable 989 or inaccessible. 991 NO_CONTEXT 8 Invalid context has been 992 supplied. 994 DEFECTIVE_TOKEN 9 A supplied token was invalid. 996 DEFECTIVE_CREDENTIAL 10 A supplied credential was 997 invalid. 999 CREDENTIALS_EXPIRED 11 The referenced credentials 1000 have expired. 1002 CONTEXT_EXPIRED 12 The context has expired. 1004 FAILURE 13 Miscellaneous failure, 1005 unspecified at the GSS-API level. 1007 BAD_QOP 14 The quality-of-protection 1008 requested could not be provided. 1010 UNAUTHORIZED 15 The operation is forbidden by 1012 GSS-API Java Bindings December 1999 1014 local security policy. 1016 UNAVAILABLE 16 The operation or option is 1017 unavailable. 1019 DUPLICATE_ELEMENT 17 The requested credential 1020 element already exists. 1022 NAME_NOT_MN 18 The provided name was not a 1023 mechanism name. 1025 OLD_TOKEN 19 The token's validity period has 1026 expired. 1028 DUPLICATE_TOKEN 20 The token was a duplicate of an 1029 earlier version. 1031 The GSS major status code of FAILURE is used to indicate that the 1032 underlying mechanism detected an error for which no specific GSS 1033 status code is defined. The mechanism-specific status code can 1034 provide more details about the error. 1036 The different major status codes that can be contained in the 1037 GSSException object thrown by the methods in this specification are 1038 the same as the major status codes returned by the corresponding 1039 calls in RFC 2078 [GSSAPIv2]. 1041 4.12.2. Mechanism-specific status codes 1043 Mechanism-specific status codes are communicated in two ways, they 1044 are part of any GSSException thrown from the mechanism specific layer 1045 to signal a fatal error, or they are part of the MessageProp object 1046 that the per-message calls use to signal non-fatal errors. 1048 A default value of 0 in either the GSSException object or the 1049 MessageProp object will be used to represent the absence of any 1050 mechanism specific status code. 1052 4.12.3. Supplementary status codes 1054 Supplementary status codes are confined to the per-message methods of 1055 the GSSContext interface. Because of the informative nature of these 1056 errors it is not appropriate to use exceptions to signal them. 1057 Instead, the per-message operations of the GSSContext interface 1058 return these values in a MessageProp object. 1060 GSS-API Java Bindings December 1999 1062 The MessageProp class defines query methods which return boolean 1063 values indicating the following supplementary states: 1065 Table: Supplementary Status Methods 1067 Method Name Meaning when "true" is returned 1069 isDuplicateToken The token was a duplicate of an 1070 earlier token. 1072 isOldToken The token's validity period has 1073 expired. 1075 isUnseqToken A later token has already been 1076 processed. 1078 isGapToken An expected per-message token was 1079 not received. 1081 "true" return value for any of the above methods indicates that the 1082 token exhibited the specified property. The application must 1083 determine the appropriate course of action for these supplementary 1084 values. They are not treated as errors by the GSS-API. 1086 4.13. Names 1088 A name is used to identify a person or entity. GSS-API authenticates 1089 the relationship between a name and the entity claiming the name. 1091 Since different authentication mechanisms may employ different 1092 namespaces for identifying their principals, GSS-API's naming support 1093 is necessarily complex in multi-mechanism environments (or even in 1094 some single-mechanism environments where the underlying mechanism 1095 supports multiple namespaces). 1097 Two distinct conceptual representations are defined for names: 1099 1) A GSS-API form represented by implementations of the GSSName 1100 interface: A single GSSName object may contain multiple names 1101 from different namespaces, but all names should refer to the 1102 same entity. An example of such an internal name would be the 1103 name returned from a call to the getName method of the 1104 GSSCredential interface, when applied to a credential containing 1105 credential elements for multiple authentication mechanisms 1106 employing different namespaces. This GSSName object will 1108 GSS-API Java Bindings December 1999 1110 contain a distinct name for the entity for each authentication 1111 mechanism. 1113 For GSS-API implementations supporting multiple namespaces, 1114 GSSName implementations must contain sufficient information to 1115 determine the namespace to which each primitive name belongs. 1117 2) Mechanism-specific contiguous byte array and string forms: 1118 Different GSSName initialization methods are provided to handle 1119 both byte array and string formats and to accommodate various 1120 calling applications and name types. These formats are capable 1121 of containing only a single name (from a single namespace). 1122 Contiguous string names are always accompanied by an object 1123 identifier specifying the namespace to which the name belongs, 1124 and their format is dependent on the authentication mechanism 1125 that employs that name. The string name forms are assumed to be 1126 printable, and may therefore be used by GSS-API applications for 1127 communication with their users. The byte array name formats are 1128 assumed to be in non-printable formats (e.g. the byte array 1129 returned from the export method of the GSSName interface). 1131 An GSSName object can be converted to a contiguous representation by 1132 using the toString method. This will guarantee that the name will be 1133 converted to a printable format. Different initialization methods in 1134 the GSSName interface are defined allowing support for multiple 1135 syntaxes for each supported namespace, and allowing users the freedom 1136 to choose a preferred name representation. The toString method 1137 should use an implementation-chosen printable syntax for each 1138 supported name-type. To obtain the printable name type, 1139 getStringNameType method can be used. 1141 There is no guarantee that calling the toString method on the GSSName 1142 interface will produce the same string form as the original imported 1143 string name. Furthermore, it is possible that the name was not even 1144 constructed from a string representation. The same applies to name- 1145 space identifiers which may not necessarily survive unchanged after a 1146 journey through the internal name-form. An example of this might be 1147 a mechanism that authenticates X.500 names, but provides an 1148 algorithmic mapping of Internet DNS names into X.500. That 1149 mechanism's implementation of GSSName might, when presented with a 1150 DNS name, generate an internal name that contained both the original 1151 DNS name and the equivalent X.500 name. Alternatively, it might only 1152 store the X.500 name. In the latter case, the toString method of 1153 GSSName would most likely generate a printable X.500 name, rather 1154 than the original DNS name. 1156 The context acceptor can obtain an GSSName object representing the 1157 entity performing the context initiation (through the usage of 1159 GSS-API Java Bindings December 1999 1161 getSrcName method). Since this name has been authenticated by a 1162 single mechanism, it contains only a single name (even if the 1163 internal name presented by the context initiator to the GSSContext 1164 object had multiple components). Such names are termed internal 1165 mechanism names, or "MN"s and the names emitted by GSSContext 1166 interface in the getSrcName and getTargName are always of this type. 1167 Since some applications may require MNs without wanting to incur the 1168 overhead of an authentication operation, creation methods are 1169 provided that take not only the name buffer and name type, but also 1170 the mechanism oid for which this name should be created. When 1171 dealing with an existing GSSName object, the canonicalize method may 1172 be invoked to convert a general internal name into an MN. 1174 GSSName objects can be compared using their equal method, which 1175 returns "true" if the two names being compared refer to the same 1176 entity. This is the preferred way to perform name comparisons 1177 instead of using the printable names that a given GSS-API 1178 implementation may support. Since GSS-API assumes that all primitive 1179 names contained within a given internal name refer to the same 1180 entity, equal can return "true" if the two names have at least one 1181 primitive name in common. If the implementation embodies knowledge 1182 of equivalence relationships between names taken from different 1183 namespaces, this knowledge may also allow successful comparisons of 1184 internal names containing no overlapping primitive elements. 1186 When used in large access control lists, the overhead of creating an 1187 GSSName object on each name and invoking the equal method on each 1188 name from the ACL may be prohibitive. As an alternative way of 1189 supporting this case, GSS-API defines a special form of the 1190 contiguous byte array name which may be compared directly (byte by 1191 byte). Contiguous names suitable for comparison are generated by the 1192 export method. Exported names may be re-imported by using the byte 1193 array constructor and specifying the NT_EXPORT_NAME as the name type 1194 object identifier. The resulting GSSName name will also be a MN. 1195 The GSSName interface defines public static Oid objects representing 1196 the standard name types. Structurally, an exported name object 1197 consists of a header containing an OID identifying the mechanism that 1198 authenticated the name, and a trailer containing the name itself, 1199 where the syntax of the trailer is defined by the individual 1200 mechanism specification. Detailed description of the format is 1201 specified in the language-independent GSS-API specification 1202 [GSSAPIv2]. 1204 Note that the results obtained by using the equals method will in 1205 general be different from those obtained by invoking canonicalize and 1206 export, and then comparing the byte array output. The first series 1207 of operation determines whether two (unauthenticated) names identify 1208 the same principal; the second whether a particular mechanism would 1210 GSS-API Java Bindings December 1999 1212 authenticate them as the same principal. These two operations will 1213 in general give the same results only for MNs. 1215 It is important to note that the above are guidelines as how GSSName 1216 implementations should behave, and are not intended to be specific 1217 requirements of how names objects must be implemented. The mechanism 1218 designers are free to decide on the details of their implementations 1219 of the GSSName interface as long as the behavior satisfies the above 1220 guidelines. 1222 4.14. Channel Bindings 1224 GSS-API supports the use of user-specified tags to identify a given 1225 context to the peer application. These tags are intended to be used 1226 to identify the particular communications channel that carries the 1227 context. Channel bindings are communicated to the GSS-API using the 1228 ChannelBinding object. The application may use byte arrays to 1229 specify the application data to be used in the channel binding as 1230 well as using instances of the InetAddress. The InetAddress for the 1231 initiator and/or acceptor can be used within an instance of a 1232 ChannelBinding. ChannelBinding can be set for the GSSContext object 1233 using the setChannelBinding method before the first call to init or 1234 accept has been performed. Unless the setChannelBinding method has 1235 been used to set the ChannelBinding for an GSSContext object, "null" 1236 ChannelBinding will be assumed. InetAddress is currently the only 1237 address type defined within the Java platform and as such, it is the 1238 only one supported within the ChannelBinding class. Applications 1239 that use other types of addresses can include them as part of the 1240 application specific data. 1242 Conceptually, the GSS-API concatenates the initiator and acceptor 1243 address information, and the application supplied byte array to form 1244 an octet string. The mechanism calculates a MIC over this octet 1245 string and binds the MIC to the context establishment token emitted 1246 by init method of the GSSContext interface. The same bindings are 1247 set by the context acceptor for its GSSContext object and during 1248 processing of the accept method a MIC is calculated in the same way. 1249 The calculated MIC is compared with that found in the token, and if 1250 the MICs differ, accept will throw a GSSException with the major 1251 code set to BAD_BINDINGS, and the context will not be established. 1252 Some mechanisms may include the actual channel binding data in the 1253 token (rather than just a MIC); applications should therefore not use 1254 confidential data as channel-binding components. 1256 Individual mechanisms may impose additional constraints on addresses 1257 that may appear in channel bindings. For example, a mechanism may 1258 verify that the initiator address field of the channel binding 1260 GSS-API Java Bindings December 1999 1262 contains the correct network address of the host system. Portable 1263 applications should therefore ensure that they either provide correct 1264 information for the address fields, or omit setting of the addressing 1265 information. 1267 4.15. Stream Objects 1269 The context object provides overloaded methods which use input and 1270 output streams as the means to convey authentication and per-message 1271 GSS-API tokens. It is important to note that the streams are 1272 expected to contain the usual GSS-API tokens which would otherwise be 1273 handled through the usage of byte arrays. The tokens are expected to 1274 have a definite start and an end. The callers are responsible for 1275 ensuring that the supplied streams will not block, or expect to block 1276 until a full token is processed by the GSS-API method. Only a single 1277 GSS-API token will be processed per invocation of the stream based 1278 method. 1280 The usage of streams allows the callers to have control and 1281 management of the supplied buffers. Because streams are non- 1282 primitive objects, the callers can make the streams as complicated or 1283 as simple as desired simply by using the streams defined in the 1284 java.io package or creating their own through the use of inheritance. 1285 This will allow for the application's greatest flexibility. 1287 4.16. Optional Parameters 1289 Whenever the application wishes to omit an optional parameter the 1290 "null" value shall be used. The detailed method descriptions 1291 indicate which parameters are optional. Methods overloading has also 1292 been used as a technique to indicate default parameters. 1294 5. Introduction to GSS-API Classes and Interfaces 1296 This section presents a brief description of the classes and 1297 interfaces that constitute the GSS-API. The implementations of these 1298 are obtained from the CLASSPATH defined by the application. If Java 1299 GSS becomes part of the standard Java API's then these classes will 1300 be available by default on all systems as part of the JRE's system 1301 classes. 1303 This section also shows the corresponding RFC 2078 functionality 1304 implemented by each of the classes. Detailed description of these 1306 GSS-API Java Bindings December 1999 1308 classes and their methods is presented in section 6. 1310 5.1. GSSManager class 1312 This abstract class serves as a factory to instantiate 1313 implementations of the GSS-API interfaces and also provides methods 1314 to make queries about underlying security mechanisms. 1316 A default implementation can be obtained using the static method 1317 getInstance(). Applications that desire to provide their own 1318 implementation of the GSSManager class can simply extend the abstract 1319 class themselves. 1321 This class contains equivalents of the following RFC 2078 routines: 1323 RFC 2078 Routine Function Section 1325 gss_import_name Create an internal name from 6.1.9- 1326 the supplied information. 6.1.12 1328 gss_acquire_cred Acquire credential 6.1.13- 1329 for use. 6.1.15 1331 gss_import_sec_context Create a previously exported 6.1.18 1332 context. 1334 gss_indicate_mechs List the mechanisms 6.1.6 1335 supported by this GSS-API 1336 implementation. 1338 gss_inquire_mechs_for_name List the mechanisms 6.1.8 1339 supporting the 1340 specified name type. 1342 gss_inquire_names_for_mech List the name types 6.1.7 1343 supported by the 1344 specified mechanism. 1346 5.2. GSSName interface 1348 GSS-API names are represented in the Java bindings through the 1349 GSSName interface. Different name formats and their definitions are 1350 identified with universal Object Identifiers (oids). The format of 1352 GSS-API Java Bindings December 1999 1354 the names can be derived based on the unique oid of each name type. 1355 The following GSS-API routines are provided by the GSSName interface: 1357 RFC 2078 Routine Function Section(s) 1359 gss_display_name Covert internal name 6.2.7 1360 representation to text format. 1362 gss_compare_name Compare two internal names. 6.2.3, 6.2.4 1364 gss_release_name Release resources associated N/A 1365 with the internal name. 1367 gss_canonicalize_name Convert an internal name to a 6.1.11, 1368 mechanism name. 1370 gss_export_name Convert a mechanism name to 6.2.6 1371 export format. 1373 gss_duplicate_name Create a copy of the internal N/A 1374 name. 1376 The gss_release_name call is not provided as Java does its own 1377 garbage collection. The gss_duplicate_name call is also redundant; 1378 the GSSName interface has no mutator methods that can change the 1379 state of the object so it is safe for sharing. 1381 5.3. GSSCredential interface 1383 The GSSCredential interface is responsible for the encapsulation of 1384 GSS-API credentials. Credentials identify a single entity and 1385 provide the necessary cryptographic information to enable the 1386 creation of a context on behalf of that entity. A single credential 1387 may contain multiple mechanism specific credentials, each referred to 1388 as a credential element. The GSSCredential interface provides the 1389 functionality of the following GSS-API routines: 1391 RFC 2078 Routine Function Section(s) 1393 gss_add_cred Constructs credentials 6.3.12 1394 incrementally. 1396 gss_inquire_cred Obtain information about 6.3.4,6.3.5 1398 GSS-API Java Bindings December 1999 1400 credential. 1402 gss_inquire_cred_by_mech Obtain per-mechanism 6.3.5-6.3.10 1403 information about 1404 a credential. 1406 gss_release_cred Disposes of credentials 6.3.3 1407 after use. 1409 5.4. GSSContext interface 1411 This interface encapsulates the functionality of context-level calls 1412 required for security context establishment and management between 1413 peers as well as the per-message services offered to applications. A 1414 context is established between a pair of peers and allows the usage 1415 of security services on a per-message basis on application data. It 1416 is created over a single security mechanism. The GSSContext 1417 interface provides the functionality of the following GSS-API 1418 routines: 1420 RFC 2078 Routine Function Section(s) 1422 gss_init_sec_context Initiate the creation of a 6.4.3, 1423 security context with a peer. 6.4.4 1425 gss_accept_sec_context Accept a security context 6.4.5, 1426 initiated by a peer. 6.4.6 1428 gss_delete_sec_context Destroy a security context. 6.4.8 1430 gss_context_time Obtain remaining context 6.4.37 1431 time. 1433 gss_inquire_context Obtain context 6.4.29 to 1434 characteristics. 6.3.42 1436 gss_wrap_size_limit Determine token-size limit 6.4.9 1437 for gss_wrap. 1439 gss_export_sec_context Transfer security context 6.4.18 1440 to another process. 1442 gss_get_mic Calculate a cryptographic 6.4.14, 1443 Message Integrity Code (MIC) 6.4.15 1445 GSS-API Java Bindings December 1999 1447 for a message. 1449 gss_verify_mic Verify integrity on a received 6.4.16, 1450 message. 6.4.17 1452 gss_wrap Attach a MIC to a message and 6.4.10, 1453 optionally encrypt the message 6.4.11 1454 content. 1456 gss_unwrap Obtain a previously wrapped 6.4.12, 1457 application message verifying 6.4.13 1458 its integrity and optionally 1459 decrypting it. 1461 The functionality offered by the gss_process_context_token routine 1462 has not been included in the Java bindings specification. The 1463 corresponding functionality of gss_delete_sec_context has also been 1464 modified to not return any peer tokens. This has been proposed in 1465 accordance to the recommendations stated in the RFC 2078 update 1466 draft. GSSContext does offer the functionality of destroying the 1467 locally-stored context information. 1469 5.5. MessageProp class 1471 This helper class is used in the per-message operations on the 1472 context. An instance of this class is created by the application and 1473 then passed into the per-message calls. In some cases, the 1474 application conveys information to the GSS-API implementation through 1475 this object and in other cases the GSS-API returns information to the 1476 application by setting it in this object. See the description of the 1477 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1478 GSSContext interfaces for details. 1480 5.6. GSSException class 1482 Exceptions are used in the Java bindings to signal fatal errors to 1483 the calling applications. This replaces the major and minor codes 1484 used in the C-bindings specification as a method of signaling 1485 failures. The GSSException class handles both minor and major codes, 1486 as well as their translation into textual representation. All GSS- 1487 API methods are declared as throwing this exception. 1489 RFC 2078 Routine Function Section 1491 GSS-API Java Bindings December 1999 1493 gss_display_status Retrieve textual 6.8.5, 6.8.6, 1494 representation of error 6.8.8, 6.8.9 1495 codes. 1497 5.7. Oid class 1499 This utility class is used to represent Universal Object Identifiers 1500 and their associated operations. GSS-API uses object identifiers to 1501 distinguish between security mechanisms and name types. This class, 1502 aside from being used whenever an object identifier is needed, 1503 implements the following GSS-API functionality: 1505 RFC 2078 Routine Function Section 1507 gss_test_oid_set_member Determine if the specified oid 6.7.5 1508 is part of a set of oids. 1510 5.8. ChannelBinding class 1512 An instance of this class is used to specify channel binding 1513 information to the GSSContext object before the start of a security 1514 context establishment. The application may use a byte array to 1515 specify application data to be used in the channel binding as well as 1516 use instances of the InetAddress. InetAddress is currently the only 1517 address type defined within the Java platform and as such, it is the 1518 only one supported within the ChannelBinding class. Applications that 1519 use other types of addresses can include them as part of the 1520 application data. 1522 6. Detailed GSS-API Class Description 1524 This section lists a detailed description of all the public methods 1525 that each of the GSS-API classes and interfaces must provide. 1527 6.1. public abstract class GSSManager 1529 The GSSManager class is an abstract class that serves as a factory 1530 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1531 also provides methods for applications to determine what mechanisms 1532 are available from the GSS implementation and what nametypes these 1533 mechanisms support. An instance of the default GSSManager subclass 1535 GSS-API Java Bindings December 1999 1537 may be obtained through the static method getInstance(), but 1538 applications are free to instantiate other subclasses of GSSManager. 1540 All but one method in this class are declared abstract. This means 1541 that subclasses have to provide the complete implementation for those 1542 methods. The only exception to this is the static method 1543 getInstance() which will have platform specific code to return an 1544 instance of the default subclass. 1546 Platform providers of GSS are required not to add any constructors to 1547 this class, private, public, or protected. This will ensure that all 1548 subclasses invoke only the default constructor provided to the base 1549 class by the compiler. 1551 A subclass extending the GSSManager abstract class may be implemented 1552 as a modular provider based layer that utilizes some well known 1553 service provider specification. The GSSManager API provides the 1554 application with methods to set provider preferences on such an 1555 implementation. These methods also allow the implementation to throw 1556 a well-defined exception in case provider based configuration is not 1557 supported. Applications that expect to be portable should be aware of 1558 this and recover cleanly by catching the exception. 1560 It is envisioned that there will be three most common ways in which 1561 providers will be used: 1563 1) The application does not care about what provider is used 1564 (the default case). 1566 2) The application wants a particular provider to be used 1567 preferentially, either for a particular mechanism or all 1568 the time, irrespective of mechanism. 1570 3) The application wants to use the locally configured 1571 providers as far as possible but if support is missing for 1572 one or more mechanisms then it wants to fall back on its 1573 own provider. 1575 The GSSManager class has two methods that enable these modes of 1576 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1577 have the effect of creating an ordered list of pairs 1578 where each pair indicates a preference of provider for a given oid. 1580 The use of these methods does not require any knowledge of whatever 1581 service provider specification the GSSManager subclass follows. It is 1582 hoped that these methods will serve the needs of most applications. 1583 Additional methods may be added to an extended GSSManager that could 1584 be part of a service provider specification that is standardized 1586 GSS-API Java Bindings December 1999 1588 later. 1590 6.1.1. Example Code 1592 GSSManager mgr = GSSManager.getInstance(); 1594 // What mechs are available to us? 1595 Oid[] supportedMechs = mgr.getMechs(); 1597 // Set a preference for the provider to be used when support is need 1598 // for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1600 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1601 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1603 Provider p = (Provider) (new com.foo.security.Provider()); 1605 mgr.addProviderAtFront(p, krb); 1606 mgr.addProviderAtFront(p, spkm1); 1608 // What name types does this spkm implementation support? 1609 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1611 6.1.2. getInstance 1613 public static GSSManager getInstance() 1615 Returns the default GSSManager implemenation. 1617 6.1.3. getMechs 1619 public abstract Oid[] getMechs() 1621 Returns an array of Oid objects indicating mechanisms available to 1622 GSS-API callers. A "null" value is returned when no mechanism are 1623 available (an example of this would be when mechanism are dynamically 1624 configured, and currently no mechanisms are installed). 1626 6.1.4. getNamesForMech 1628 public abstract Oid[] getNamesForMech(Oid mech) 1630 GSS-API Java Bindings December 1999 1632 throws GSSException 1634 Returns name type Oid's supported by the specified mechanism. 1636 Parameters: 1638 mech The Oid object for the mechanism to query. 1640 6.1.5. getMechsForName 1642 public abstract Oid[] getMechsForName(Oid nameType) 1644 Returns an array of Oid objects corresponding to the mechanisms that 1645 support the specific name type. "null" is returned when no 1646 mechanisms are found to support the specified name type. 1648 Parameters: 1650 nameType The Oid object for the name type. 1652 6.1.6. createName 1654 public abstract GSSName createName(String nameStr, Oid nameSpace) 1655 throws GSSException 1657 Factory method to convert a contiguous string name from the specified 1658 namespace to an GSSName object. In general, the GSSName object 1659 created will not be an MN; two examples that are exceptions to this 1660 are when the namespace type parameter indicates NT_EXPORT_NAME or 1661 when the GSS-API implementation is not multi-mechanism. 1663 Parameters: 1665 nameStr The string representing a printable form of the name 1666 to create. 1668 nameType The Oid specifying the namespace of the printable name 1669 supplied. Note that nameType serves to describe and 1670 qualify the interpretation of the input nameStr, it 1671 does not necessarily imply a type for the output 1672 GSSName implementation. "null" value can be used to 1673 specify that a mechanism specific default printable 1674 syntax should be assumed by each mechanism that 1675 examines nameStr. 1677 GSS-API Java Bindings December 1999 1679 6.1.7. createName 1681 public abstract GSSName createName(byte name[], Oid nameType) 1682 throws GSSException 1684 Factory method to convert a contiguous byte array containing a name 1685 from the specified namespace to an GSSName object. In general, the 1686 GSSName object created will not be an MN; two examples that are 1687 exceptions to this are when the namespace type parameter indicates 1688 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1689 mechanism. 1691 Parameters: 1693 name The byte array containing the name to create. 1695 nameType The Oid specifying the namespace of the name supplied 1696 in the byte array. Note that nameType serves to 1697 describe and qualify the interpretation of the input 1698 name byte array, it does not necessarily imply a type 1699 for the output GSSName implementation. "null" value 1700 can be used to specify that a mechanism specific 1701 default syntax should be assumed by each mechanism 1702 that examines the byte array. 1704 6.1.8. createName 1706 public abstract GSSName createName(String nameStr, Oid nameType, 1707 Oid mechType) throws GSSException 1709 Factory method to convert a contiguous string name from the specified 1710 namespace to an GSSName object that is a mechanism name (MN). In 1711 other words, this method is a utility that does the equivalent of two 1712 steps: the createName described in 6.1.7 and then also the 1713 GSSName.canonicalize() described in 6.2.5. 1715 Parameters: 1717 nameStr The string representing a printable form of the name 1718 to create. 1720 nameType The Oid specifying the namespace of the printable name 1721 supplied. Note that nameType serves to describe and 1722 qualify the interpretation of the input nameStr, it 1723 does not necessarily imply a type for the output 1724 GSSName implementation. "null" value can be used to 1726 GSS-API Java Bindings December 1999 1728 specify that a mechanism specific default printable 1729 syntax should be assumed when the mechanism examines 1730 nameStr. 1732 mechType Oid specifying the mechanism for which this name 1733 should be created. 1735 6.1.9. createName 1737 public abstract createName(byte name[], Oid nameType, Oid mechType) 1738 throws GSSException 1740 Factory method to convert a contiguous byte array containing a name 1741 from the specified namespace to an GSSName object that is an MN. In 1742 other words, this method is a utility that does the equivalent of two 1743 steps: the createName described in 6.1.8 and then also the 1744 GSSName.canonicalize() described in 6.2.5. 1746 Parameters: 1748 name The byte array representing the name to create. 1750 nameType The Oid specifying the namespace of the name supplied 1751 in the byte array. Note that nameType serves to 1752 describe and qualify the interpretation of the input 1753 name byte array, it does not necessarily imply a type 1754 for the output GSSName implementation. "null" value 1755 can be used to specify that a mechanism specific 1756 default syntax should be assumed by each mechanism 1757 that examines the byte array. 1759 mechType Oid specifying the mechanism for which this name 1760 should be created. 1762 6.1.10. createCredential 1764 public abstract GSSCredential createCredential (int usage) 1765 throws GSSException 1767 Factory method for acquiring default credentials. This will cause 1768 the GSS-API to use system specific defaults for the set of 1769 mechanisms, name, and an INDEFINITE lifetime. 1771 Parameters: 1773 usage The intended usage for this credential object. The 1775 GSS-API Java Bindings December 1999 1777 value of this parameter must be one of: 1778 GSSCredential.ACCEPT_AND_INITIATE, 1779 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1781 6.1.11. createCredential 1783 public abstract GSSCredential createCredential (GSSName aName, 1784 int lifetime, Oid mechOid, int usage) 1785 throws GSSException 1787 Factory method for acquiring a single mechanism credential. 1789 Parameters: 1791 aName Name of the principal for whom this credential is to 1792 be acquired. Use "null" to specify the default 1793 principal. 1795 lifetime The number of seconds that credentials should remain 1796 valid. Use GSSCredential.INDEFINITE to request that 1797 the credentials have the maximum permitted lifetime. 1799 mechOid The oid of the desired mechanism. Use "(Oid) null" to 1800 request the default mechanism(s). 1802 usage The intended usage for this credential object. The 1803 value of this parameter must be one of: 1804 GSSCredential.ACCEPT_AND_INITIATE, 1805 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1807 6.1.12. createCredential 1809 public abstract GSSCredential createCredential(GSSName aName, 1810 int lifetime, Oid mechs[], int usage) 1811 throws GSSException 1813 Factory method for acquiring credentials over a set of mechanisms. 1814 Acquires credentials for each of the mechanisms specified in the 1815 array called mechs. To determine the list of mechanisms' for which 1816 the acquisition of credentials succeeded, the caller should use the 1817 GSSCredential.getMechs() method. 1819 Parameters: 1821 aName Name of the principal for whom this credential is to 1822 be acquired. Use "null" to specify the default 1824 GSS-API Java Bindings December 1999 1826 principal. 1828 lifetime The number of seconds that credentials should remain 1829 valid. Use GSSCredential.INDEFINITE to request that 1830 the credentials have the maximum permitted lifetime. 1832 mechOid The array of mechanisms over which the credential is 1833 to be acquired. Use "(Oid[]) null" for requesting a 1834 system specific default set of mechanisms. 1836 usage The intended usage for this credential object. The 1837 value of this parameter must be one of: 1838 GSSCredential.ACCEPT_AND_INITIATE, 1839 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1841 6.1.13. createContext 1843 public abstract GSSContext createContext(GSSName peer, Oid mechOid, 1844 GSSCredential myCred, int lifetime) 1845 throws GSSException 1847 Factory method for creating a context on the initiator's side. 1848 Context flags may be modified through the mutator methods prior to 1849 calling GSSContext.initSecContext(). 1851 Parameters: 1853 peer Name of the target peer. 1855 mechOid Oid of the desired mechanism. Use "(Oid) null" to 1856 request default mechanism. 1858 myCred Credentials of the initiator. Use "null" to act as a 1859 default initiator principal. 1861 lifetime The request lifetime, in seconds, for the credential. 1863 6.1.14. createContext 1865 public abstract GSSContext createContext(GSSCredential myCred) 1866 throws GSSException 1868 Factory method for creating a context on the acceptor' side. The 1869 context's properties will be determined from the input token supplied 1870 to the accept method. 1872 GSS-API Java Bindings December 1999 1874 Parameters: 1876 myCred Credentials for the acceptor. Use "null" to act as a 1877 default acceptor principal. 1879 6.1.15. createContext 1881 public abstract GSSContext createContext(byte [] interProcessToken) 1882 throws GSSException 1884 Factory method for creating a previously exported context. The 1885 context properties will be determined from the input token and can't 1886 be modified through the set methods. 1888 Parameters: 1890 interProcessToken 1891 The token previously emitted from the export method. 1893 6.1.16. addProviderAtFront 1895 public abstract void addProviderAtFront(Provider p, Oid mech) 1896 throws GSSException 1898 This method is used to indicate to the GSSManager that the 1899 application would like a particular provider to be used ahead of all 1900 others when support is desired for the given mechanism. When a value 1901 of null is used instead of an Oid for the mechanism, the GSSManager 1902 must use the indicated provider ahead of all others no matter what 1903 the mechanism is. Only when the indicated provider does not support 1904 the needed mechanism should the GSSManager move on to a different 1905 provider. 1907 Calling this method repeatedly preserves the older settings but 1908 lowers them in preference thus forming an ordered list of provider 1909 and Oid pairs that grows at the top. 1911 Calling addProviderAtFront with a null Oid will remove all previous 1912 preferences that were set for this provider in the GSSManager 1913 instance. Calling addProviderAtFront with a non-null Oid will remove 1914 any previous preference that was set using this mechanism and this 1915 provider together. 1917 If the GSSManager implementation does not support an SPI with a 1918 pluggable provider architecture it should throw a GSSException with 1919 the status code GSSException.UNAVAILABLE to indicate that the 1921 GSS-API Java Bindings December 1999 1923 operation is unavailable. 1925 Parameters: 1927 p The provider instance that should be used whenever 1928 support is needed for mech. 1930 mech The mechanism for which the provider is being set 1932 6.1.16.1. Example Code 1934 Suppose an application desired that the provider A always be checked 1935 first when any mechanism is needed, it would call: 1937 GSSManager mgr = GSSManager.getInstance(); 1938 // mgr may at this point have its own pre-configured list 1939 // of provider preferences. The following will prepend to 1940 // any such list: 1942 mgr.addProviderAtFront(A, null); 1944 Now if it also desired that the mechanism of Oid m1 always be 1945 obtained from the provider B before the previously set A was checked, 1946 it would call: 1948 mgr.addProviderAtFront(B, m1); 1950 The GSSManager would then first check with B if m1 was needed. In 1951 case B did not provide support for m1, the GSSManager would continue 1952 on to check with A. If any mechanism m2 is needed where m2 is 1953 different from m1 then the GSSManager would skip B and check with A 1954 directly. 1956 Suppose at a later time the following call is made to the same 1957 GSSManager instance: 1959 mgr.addProviderAtFront(B, null) 1961 then the previous setting with the pair (B, m1) is subsumed by this 1962 and should be removed. Effectively the list of preferences now 1963 becomes {(B, null), (A, null), 1964 ... //followed by the pre-configured list. 1966 Please note, however, that the following call: 1968 mgr.addProviderAtFront(A, m3) 1970 GSS-API Java Bindings December 1999 1972 does not subsume the previous setting of (A, null) and the list will 1973 effectively become {(A, m3), (B, null), (A, null), ...} 1975 6.1.17. addProviderAtEnd 1977 public abstract addProviderAtEnd(Provider p, Oid mech) 1978 throws GSSException 1980 This method is used to indicate to the GSSManager that the 1981 application would like a particular provider to be used if no other 1982 provider can be found that supports the given mechanism. When a value 1983 of null is used instead of an Oid for the mechanism, the GSSManager 1984 must use the indicated provider for any mechanism. 1986 Calling this method repeatedly preserves the older settings but 1987 raises them above newer ones in preference thus forming an ordered 1988 list of providers and Oid pairs that grows at the bottom. Thus the 1989 older provider settings will be utilized first before this one is. 1991 If there are any previously existing preferences that conflict with 1992 the preference being set here, then the GSSManager should ignore this 1993 request. 1995 If the GSSManager implementation does not support an SPI with a 1996 pluggable provider architecture it should throw a GSSException with 1997 the status code GSSException.UNAVAILABLE to indicate that the 1998 operation is unavailable. 2000 Parameters: 2002 p The provider instance that should be used whenever 2003 support is needed for mech. 2005 mech The mechanism for which the provider is being set 2007 6.1.17.1. Example Code 2009 Suppose an application desired that when a mechanism of Oid m1 is 2010 needed the system default providers always be checked first, and only 2011 when they do not support m1 should a provider A be checked. It would 2012 then make the call: 2014 GSSManager mgr = GSSManager.getInstance(); 2016 mgr.addProviderAtEnd(A, m1); 2018 GSS-API Java Bindings December 1999 2020 Now, if it also desired that for all mechanisms the provider B be 2021 checked after all configured providers have been checked, it would 2022 then call: 2024 mgr.addProviderAtEnd(B, null); 2026 Effectively the list of preferences now becomes {..., (A, m1), (B, 2027 null)}. 2029 Suppose at a later time the following call is made to the same 2030 GSSManager instance: 2032 mgr.addProviderAtEnd(B, m2) 2034 then the previous setting with the pair (B, null) subsumes this and 2035 therefore this request should be ignored. The same would happen if a 2036 request is made for the already existing pairs of (A, m1) or (B, 2037 null). 2039 Please note, however, that the following call: 2041 mgr.addProviderAtEnd(A, null) 2043 is not subsumed by the previous setting of (A, m1) and the list will 2044 effectively become {..., (A, m1), (B, null), (A, null)} 2046 6.2. public interface GSSName 2048 This interface encapsulates a single GSS-API principal entity. 2049 Different name formats and their definitions are identified with 2050 universal Object Identifiers (Oids). The format of the names can be 2051 derived based on the unique oid of its namespace type. 2053 6.2.1. Example Code 2055 Included below are code examples utilizing the GSSName interface. 2056 The code below creates a GSSName, converts it to a mechanism name 2057 (MN), performs a comparison, obtains a printable representation of 2058 the name, exports it and then re-imports to obtain a new GSSName. 2060 GSSManager mgr = new GSSManager(); 2062 // create a host based service name 2063 GSSName name = mgr.createName("service@host", 2065 GSS-API Java Bindings December 1999 2067 GSSName.NT_HOSTBASED_SERVICE); 2069 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 2071 GSSName mechName = name.canonicalize(krb5); 2073 // the above two steps are equivalent to the following 2074 GSSName mechName = mgr.createName("service@host", 2075 GSSName.NT_HOSTBASED_SERVICE, krb5); 2077 // perform name comparison 2078 if (name.equals(mechName)) 2079 print("Names are equals."); 2081 // obtain textual representation of name and its printable 2082 // name type 2083 print(mechName.toString() + 2084 mechName.getStringNameType().toString()); 2086 // export and re-import the name 2087 byte [] exportName = mechName.export(); 2089 // create a new name object from the exported buffer 2090 GSSName newName = mgr.createName(exportName, 2091 GSSName.NT_EXPORT_NAME); 2093 6.2.2. Static Constants 2095 public static final Oid NT_HOSTBASED_SERVICE 2097 Oid indicating a host-based service name form. It is used to 2098 represent services associated with host computers. This name form is 2099 constructed using two elements, "service" and "hostname", as follows: 2101 service@hostname 2103 Values for the "service" element are registered with the IANA. It 2104 represents the following value: { 1(iso), 3(org), 6(dod), 2105 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) } 2107 public static final Oid NT_USER_NAME 2109 Name type to indicate a named user on a local system. It represents 2110 the following value: { iso(1) member-body(2) United States(840) 2111 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2113 GSS-API Java Bindings December 1999 2115 public static final Oid NT_MACHINE_UID_NAME 2117 Name type to indicate a numeric user identifier corresponding to a 2118 user on a local system. (e.g. Uid). It represents the following 2119 value: { iso(1) member-body(2) United States(840) mit(113554) 2120 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2122 public static final Oid NT_STRING_UID_NAME 2124 Name type to indicate a string of digits representing the numeric 2125 user identifier of a user on a local system. It represents the 2126 following value: { iso(1) member-body(2) United States(840) 2127 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2129 public static final Oid NT_ANONYMOUS 2131 Name type for representing an anonymous entity. It represents the 2132 following value: { 1(iso), 3(org), 6(dod), 1(internet), 5(security), 2133 6(nametypes), 3(gss-anonymous-name) } 2135 public static final Oid NT_EXPORT_NAME 2137 Name type used to indicate an exported name produced by the export 2138 method. It represents the following value: { 1(iso), 3(org), 6(dod), 2139 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) } 2141 6.2.3. equals 2143 public boolean equals(GSSName another) throws GSSException 2145 Compares two GSSName objects to determine whether they refer to the 2146 same entity. This method may throw a GSSException when the names 2147 cannot be compared. If either of the names represents an anonymous 2148 entity, the method will return "false". 2150 Parameters: 2152 another GSSName object to compare with. 2154 6.2.4. equals 2156 public boolean equals(Object another) 2158 GSS-API Java Bindings December 1999 2160 A variation of the equals method described in 6.2.3 that is provided 2161 to override the Object.equals() method that the implementing class 2162 will inherit. The behaviour is exactly the same as that in 6.2.3 2163 except that no GSSException is thrown; instead, false will be 2164 returned in the situation where an error occurs. (Note that the Java 2165 language specification requires that two objects that are equal 2166 according to the equals(Object) method must return the same integer 2167 result when the hashCode() method is called on them.) 2169 Parameters: 2171 another GSSName object to compare with. 2173 6.2.5. canonicalize 2175 public GSSName canonicalize(Oid mechOid) throws GSSException 2177 Creates a mechanism name (MN) from an arbitrary internal name. This 2178 is equivalent to using the factory methods described in 6.1.9 or 2179 6.1.10 that take the mechanism name as one of their parameters. 2181 Parameters: 2183 mechOid The oid for the mechanism for which the canonical form 2184 of the name is requested. 2186 6.2.6. export 2188 public byte[] export() throws GSSException 2190 Returns a canonical contiguous byte representation of a mechanism 2191 name (MN), suitable for direct, byte by byte comparison by 2192 authorization functions. If the name is not an MN, implementations 2193 may throw a GSSException with the NAME_NOT_MN status code. If an 2194 implementation chooses not to throw an exception, it should use some 2195 system specific default mechanism to canonicalize the name and then 2196 export it. The format of the header of the output buffer is 2197 specified in RFC 2078. 2199 6.2.7. toString 2201 public String toString() 2203 Returns a textual representation of the GSSName object. To retrieve 2204 the printed name format, which determines the syntax of the returned 2206 GSS-API Java Bindings December 1999 2208 string, the getStringNameType method can be used. 2210 6.2.8. getStringNameType 2212 public Oid getStringNameType() throws GSSException 2214 Returns the oid representing the type of name returned through the 2215 toString method. Using this oid, the syntax of the printable name 2216 can be determined. 2218 6.2.9. isAnonymous 2220 public boolean isAnonymous() 2222 Tests if this name object represents an anonymous entity. Returns 2223 "true" if this is an anonymous name. 2225 6.2.10. isMN 2227 public boolean isMN() 2229 Tests if this name object contains only one mechanism element and is 2230 thus a mechanism name as defined by RFC 2078. 2232 6.3. public interface GSSCredential implements Cloneable 2234 This interface encapsulates the GSS-API credentials for an entity. A 2235 credential contains all the necessary cryptographic information to 2236 enable the creation of a context on behalf of the entity that it 2237 represents. It may contain multiple, distinct, mechanism specific 2238 credential elements, each containing information for a specific 2239 security mechanism, but all referring to the same entity. 2241 A credential may be used to perform context initiation, acceptance, 2242 or both. 2244 GSS-API implementations must impose a local access-control policy on 2245 callers to prevent unauthorized callers from acquiring credentials to 2246 which they are not entitled. GSS-API credential creation is not 2247 intended to provide a "login to the network" function, as such a 2248 function would involve the creation of new credentials rather than 2249 merely acquiring a handle to existing credentials. Such functions, 2250 if required, should be defined in implementation-specific extensions 2252 GSS-API Java Bindings December 1999 2254 to the API. 2256 If credential acquisition is time-consuming for a mechanism, the 2257 mechanism may choose to delay the actual acquisition until the 2258 credential is required (e.g. by GSSContext). Such mechanism- 2259 specific implementation decisions should be invisible to the calling 2260 application; thus the query methods immediately following the 2261 creation of a credential object must return valid credential data, 2262 and may therefore incur the overhead of a deferred credential 2263 acquisition. 2265 Applications will create a credential object passing the desired 2266 parameters. The application can then use the query methods to obtain 2267 specific information about the instantiated credential object 2268 (equivalent to the gss_inquire routines). When the credential is no 2269 longer needed, the application should call the dispose (equivalent to 2270 gss_release_cred) method to release any resources held by the 2271 credential object and to destroy any cryptographically sensitive 2272 information. 2274 Classes implementing this interface also implement the Cloneable 2275 interface. This indicates the the class will support the clone() 2276 method that will allow the creation of duplicate credentials. This 2277 is useful when called just before the add() call to retain a copy of 2278 the original credential. 2280 6.3.1. Example Code 2282 This example code demonstrates the creation of a GSSCredential 2283 implementation for a specific entity, querying of its fields, and its 2284 release when it is no longer needed. 2286 GSSManager mgr = new GSSManager(); 2288 // start by creating a name object for the entity 2289 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2291 // now acquire credentials for the entity 2292 GSSCredential cred = mgr.createCredential(name, 2293 GSSCredential.ACCEPT_ONLY); 2295 // display credential information - name, remaining lifetime, 2296 // and the mechanisms it has been acquired over 2297 print(cred.getName().toString()); 2298 print(cred.getRemainingLifetime()); 2300 GSS-API Java Bindings December 1999 2302 Oid [] mechs = cred.getMechs(); 2303 if (mechs != null) { 2304 for (int i = 0; i < mechs.length; i++) 2305 print(mechs[i].toString()); 2306 } 2308 // release system resources held by the credential 2309 cred.dispose(); 2311 6.3.2. Static Constants 2313 public static final int INITIATE_AND_ACCEPT 2315 Credential usage flag requesting that it be able to be used for both 2316 context initiation and acceptance. 2318 public static final int INITIATE_ONLY 2320 Credential usage flag requesting that it be able to be used for 2321 context initiation only. 2323 public static final int ACCEPT_ONLY 2325 Credential usage flag requesting that it be able to be used for 2326 context acceptance only. 2328 public static final int INDEFINITE 2330 A lifetime constant representing indefinite credential lifetime. 2331 This value must be set to the maximum integer value in Java - 2332 Integer.MAX_VALUE. 2334 6.3.3. dispose 2336 public void dispose() throws GSSException 2338 Releases any sensitive information that the GSSCredential object may 2339 be containing. Applications should call this method as soon as the 2340 credential is no longer needed to minimize the time any sensitive 2341 information is maintained. 2343 GSS-API Java Bindings December 1999 2345 6.3.4. getName 2347 public GSSName getName() throws GSSException 2349 Retrieves the name of the entity that the credential asserts. 2351 6.3.5. getName 2353 public GSSName getName(Oid mechOID) throws GSSException 2355 Retrieves a mechanism name of the entity that the credential asserts. 2356 Equivalent to calling canonicalize() on the name returned by 7.3.3. 2358 Parameters: 2360 mechOID The mechanism for which information should be 2361 returned. 2363 6.3.6. getRemainingLifetime 2365 public int getRemainingLifetime() throws GSSException 2367 Returns the remaining lifetime in seconds for a credential. The 2368 remaining lifetime is the minimum lifetime for any of the underlying 2369 credential mechanisms. A return value of GSSCredential.INDEFINITE 2370 indicates that the credential does not expire. A return value of 0 2371 indicates that the credential is already expired. 2373 6.3.7. getRemainingInitLifetime 2375 public int getRemainingInitLifetime(Oid mech) throws GSSException 2377 Returns the remaining lifetime is seconds for the credential to 2378 remain capable of initiating security contexts under the specified 2379 mechanism. A return value of GSSCredential.INDEFINITE indicates that 2380 the credential does not expire for context initiation. A return 2381 value of 0 indicates that the credential is already expired. 2383 Parameters: 2385 mechOID The mechanism for which information should be 2386 returned. 2388 GSS-API Java Bindings December 1999 2390 6.3.8. getRemainingAcceptLifetime 2392 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2394 Returns the remaining lifetime is seconds for the credential to 2395 remain capable of accepting security contexts under the specified 2396 mechanism. A return value of GSSCredential.INDEFINITE indicates that 2397 the credential does not expire for context acceptance. A return 2398 value of 0 indicates that the credential is already expired. 2400 Parameters: 2402 mechOID The mechanism for which information should be 2403 returned. 2405 6.3.9. getUsage 2407 public int getUsage() throws GSSException 2409 Returns the credential usage flag. The return value will be one of 2410 GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or 2411 GSSCredential.INITIATE_AND_ACCEPT. 2413 6.3.10. getUsage 2415 public int getUsage(Oid mechOID) throws GSSException 2417 Returns the credential usage flag for the specified credential 2418 mechanism. The return value will be one of 2419 GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or 2420 GSSCredential.INITIATE_AND_ACCEPT. 2422 Parameters: 2424 mechOID The mechanism for which information should be 2425 returned. 2427 6.3.11. getMechs 2429 public Oid[] getMechs() throws GSSException 2431 Returns an array of mechanisms supported by this credential. 2433 GSS-API Java Bindings December 1999 2435 6.3.12. add 2437 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2438 Oid mech, int usage) throws GSSException 2440 Adds a mechanism specific credential-element to an existing 2441 credential. This method allows the construction of credentials one 2442 mechanism at a time. 2444 This routine is envisioned to be used mainly by context acceptors 2445 during the creation of acceptance credentials which are to be used 2446 with a variety of clients using different security mechanisms. 2448 This routine adds the new credential element "in-place". To add the 2449 element in a new credential, first call clone() to obtain a copy of 2450 this credential, then call its add() method. 2452 Parameters: 2454 aName Name of the principal for whom this credential is to 2455 be acquired. Use "null" to specify the default 2456 principal. 2458 initLifetime 2459 The number of seconds that credentials should remain 2460 valid for initiating of security contexts. Use 2461 GSSCredential.INDEFINITE to request that the 2462 credentials have the maximum permitted lifetime. 2464 acceptLifetime 2465 The number of seconds that credentials should remain 2466 valid for accepting of security contexts. Use 2467 GSSCredential.INDEFINITE to request that the 2468 credentials have the maximum permitted lifetime. 2470 mechOid The mechanisms over which the credential is to be 2471 acquired. 2473 usage The intended usage for this credential object. The 2474 value of this parameter must be one of: 2475 GSSCredential.ACCEPT_AND_INITIATE, 2476 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 2478 6.3.13. equals 2480 public boolean equals(Object another) 2482 GSS-API Java Bindings December 1999 2484 Tests if this GSSCredential refers to the same entity as the supplied 2485 object. The two credentials must be acquired over the same 2486 mechanisms and must refer to the same principal. Returns "true" if 2487 the two GSSCredentials refer to the same entity; "false" otherwise. 2488 (Note that the Java language specification requires that two objects 2489 that are equal according to the equals(Object) method must return the 2490 same integer result when the hashCode() method is called on them.) 2492 Parameters: 2494 another Another GSSCredential object for comparison. 2496 6.4. public interface GSSContext 2498 This interface encapsulates the GSS-API security context and provides 2499 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2500 available over the context. Security contexts are established 2501 between peers using locally acquired credentials. Multiple contexts 2502 may exist simultaneously between a pair of peers, using the same or 2503 different set of credentials. GSS-API functions in a manner 2504 independent of the underlying transport protocol and depends on its 2505 calling application to transport its tokens between peers. 2507 Before the context establishment phase is initiated, the context 2508 initiator may request specific characteristics desired of the 2509 established context. These can be set using the set methods. After 2510 the context is established, the caller can check the actual 2511 characteristic and services offered by the context using the query 2512 methods. 2514 The context establishment phase begins with the first call to the 2515 init method by the context initiator. During this phase the 2516 initSecContext and acceptSecContext methods will produce GSS-API 2517 authentication tokens which the calling application needs to send to 2518 its peer. If an error occurs at any point, an exception will get 2519 thrown and the code will start executing in a catch block. If not, 2520 the normal flow of code continues and the application can make a call 2521 to the isEstablished() method. If this method returns false it 2522 indicates that a token is needed from its peer in order to continue 2523 the context establishment phase. A return value of true signals that 2524 the local end of the context is established. This may still require 2525 that a token be sent to the peer, if one is produced by GSS-API. 2526 During the context establishment phase, the isProtReady() method may 2527 be called to determine if the context can be used for the per-message 2528 operations. This allows applications to use per-message operations 2530 GSS-API Java Bindings December 1999 2532 on contexts which aren't fully established. 2534 After the context has been established or the isProtReady() method 2535 returns "true", the query routines can be invoked to determine the 2536 actual characteristics and services of the established context. The 2537 application can also start using the per-message methods of wrap and 2538 getMIC to obtain cryptographic operations on application supplied 2539 data. 2541 When the context is no longer needed, the application should call 2542 dispose to release any system resources the context may be using. 2544 6.4.1. Example Code 2546 The example code presented below demonstrates the usage of the 2547 GSSContext interface for the initiating peer. Different operations 2548 on the GSSContext object are presented, including: object 2549 instantiation, setting of desired flags, context establishment, query 2550 of actual context flags, per-message operations on application data, 2551 and finally context deletion. 2553 GSSManager mgr = new GSSManager(); 2555 // start by creating the name for a service entity 2556 GSSName targetName = mgr.createName("service@host", 2557 GSSName.NT_HOSTBASED_SERVICE); 2559 // create a context using default credentials for the above entity 2560 // and the implementation specific default mechanism 2561 GSSContext context = mgr.createContext(targetName, 2562 null, /* default mechanism */ 2563 null, /* default credentials */ 2564 GSSContext.INDEFINITE); 2566 // set desired context options - all others are false by default 2567 context.requestConf(true); 2568 context.requestMutualAuth(true); 2569 context.requestReplayDet(true); 2570 context.requestSequenceDet(true); 2572 // establish a context between peers - using byte arrays 2573 byte []inTok = new byte[0]; 2575 try { 2576 do { 2577 byte[] outTok = context.initSecContext(inTok, 0, 2579 GSS-API Java Bindings December 1999 2581 inTok.length); 2583 // send the token if present 2584 if (outTok != null) 2585 sendToken(outTok); 2587 // check if we should expect more tokens 2588 if (context.isEstablished()) 2589 break; 2591 // another token expected from peer 2592 inTok = readToken(); 2594 } while (true); 2596 } catch (GSSException e) { 2597 print("GSSAPI error: " + e.getMessage()); 2598 } 2600 // display context information 2601 print("Remaining lifetime in seconds = " + context.getLifetime()); 2602 print("Context mechanism = " + context.getMech().toString()); 2603 print("Initiator = " + context.getSrcName().toString()); 2604 print("Acceptor = " + context.getTargName().toString()); 2606 if (context.getConfState()) 2607 print("Confidentiality security service available"); 2609 if (context.getIntegState()) 2610 print("Integrity security service available"); 2612 // perform wrap on an application supplied message, appMsg, 2613 // using QOP = 0, and requesting privacy service 2614 byte [] appMsg ... 2616 MessageProp mProp = new MessageProp(0, true); 2618 byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2620 if (mProp.getPrivacy()) 2621 print("Message protected with privacy."); 2623 sendToken(tok); 2625 // release the local-end of the context 2626 context.dispose(); 2628 GSS-API Java Bindings December 1999 2630 6.4.2. Static Constants 2632 public static final int INDEFINITE 2634 A lifetime constant representing indefinite context lifetime. This 2635 value must be set to the maximum integer value in Java - 2636 Integer.MAX_VALUE. 2638 6.4.3. initSecContext 2640 public byte[] initSecContext(byte inputBuf[], int offset, int len) 2641 throws GSSException 2643 Called by the context initiator to start the context creation 2644 process. This is equivalent to the stream based method except that 2645 the token buffers are handled as byte arrays instead of using stream 2646 objects. This method may return an output token which the 2647 application will need to send to the peer for processing by the 2648 accept call. "null" return value indicates that no token needs to be 2649 sent to the peer. The application can call isEstablished() to 2650 determine if the context establishment phase is complete for this 2651 peer. A return value of "false" from isEstablished() indicates that 2652 more tokens are expected to be supplied to the initSecContext() 2653 method. Note that it is possible that the initSecContext() method 2654 return a token for the peer, and isEstablished() return "true" also. 2655 This indicates that the token needs to be sent to the peer, but the 2656 local end of the context is now fully established. 2658 Upon completion of the context establishment, the available context 2659 options may be queried through the get methods. 2661 Parameters: 2663 inputBuf Token generated by the peer. This parameter is ignored 2664 on the first call. 2666 offset The offset within the inputBuf where the token begins. 2668 len The length of the token within the inputBuf (starting 2669 at the offset). 2671 6.4.3.1. Example Code 2673 // Create a new GSSContext implementation object. 2674 // GSSContext wrapper implements interface GSSContext. 2676 GSS-API Java Bindings December 1999 2678 GSSContext context = mgr.createContext(...); 2680 byte []inTok = new byte[0]; 2682 try { 2684 do { 2685 byte[] outTok = context.initSecContext(inTok, 0, 2686 inTok.length); 2688 // send the token if present 2689 if (outTok != null) 2690 sendToken(outTok); 2692 // check if we should expect more tokens 2693 if (context.isEstablished()) 2694 break; 2696 // another token expected from peer 2697 inTok = readToken(); 2698 } while (true); 2700 } catch (GSSException e) { 2701 print("GSSAPI error: " + e.getMessage()); 2702 } 2704 6.4.4. initSecContext 2706 public int initSecContext(InputStream inStream, 2707 OutputStream outStream) throws GSSException 2709 Called by the context initiator to start the context creation 2710 process. This is equivalent to the byte array based method. This 2711 method may write an output token to the outStream, which the 2712 application will need to send to the peer for processing by the 2713 accept call. 0 bytes written to the output stream indicate that no 2714 token needs to be sent to the peer. The application can call 2715 isEstablished() to determine if the context establishment phase is 2716 complete for this peer. A return value of "false" from isEstablished 2717 indicates that more tokens are expected to be supplied to the 2718 initSecContext method. Note that it is possible that the 2719 initSecContext() method return a token for the peer, and 2720 isEstablished() return "true" also. This indicates that the token 2721 needs to be sent to the peer, but the local end of the context is now 2723 GSS-API Java Bindings December 1999 2725 fully established. 2727 The GSS-API authentication tokens contain a definitive start and end. 2728 This method will attempt to read one of these tokens per invocation, 2729 and may block on the stream if only part of the token is available. 2731 Upon completion of the context establishment, the available context 2732 options may be queried through the get methods. 2734 Parameters: 2736 inStream Contains the token generated by the peer. This 2737 parameter is ignored on the first call. 2739 outStream Output stream where the output token will be written. 2740 During the final stage of context establishment, there 2741 may be no bytes written. 2743 6.4.4.1. Example Code 2745 // Create a new GSSContext implementation object. 2746 // GSSContext wrapper implements interface GSSContext. 2747 GSSContext context = mgr.createContext(...); 2749 // use standard java.io stream objects 2750 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2751 ByteArrayInputStream is = null; 2753 try { 2755 do { 2756 context.initSecContext(is, os); 2758 // send token if present 2759 if (os.size() > 0) 2760 sendToken(os); 2762 // check if we should expect more tokens 2763 if (context.isEstablished()) 2764 break; 2766 // another token expected from peer 2767 is = recvToken(); 2769 } while (true); 2771 GSS-API Java Bindings December 1999 2773 } catch (GSSException e) { 2774 print("GSSAPI error: " + e.getMessage()); 2775 } 2777 6.4.5. acceptSecContext 2779 public byte[] acceptSecContext(byte inTok[], int offset, int len) 2780 throws GSSException 2782 Called by the context acceptor upon receiving a token from the peer. 2783 This call is equivalent to the stream based method except that the 2784 token buffers are handled as byte arrays instead of using stream 2785 objects. 2787 This method may return an output token which the application will 2788 need to send to the peer for further processing by the init call. 2789 "null" return value indicates that no token needs to be sent to the 2790 peer. The application can call isEstablished() to determine if the 2791 context establishment phase is complete for this peer. A return 2792 value of "false" from isEstablished() indicates that more tokens are 2793 expected to be supplied to this method. 2795 Note that it is possible that acceptSecContext() return a token for 2796 the peer, and isEstablished() return "true" also. This indicates 2797 that the token needs to be sent to the peer, but the local end of the 2798 context is now fully established. 2800 Upon completion of the context establishment, the available context 2801 options may be queried through the get methods. 2803 Parameters: 2805 inTok Token generated by the peer. 2807 offset The offset within the inTok where the token begins. 2809 len The length of the token within the inTok (starting at 2810 the offset). 2812 6.4.5.1. Example Code 2814 // acquire server credentials 2815 GSSCredential server = mgr.createCredential(...); 2817 GSS-API Java Bindings December 1999 2819 // create acceptor GSS-API context fromthe default provider 2820 GSSContext context = mgr.createContext(server, null); 2822 try { 2823 do { 2824 byte [] inTok = readToken(); 2826 byte []outTok = context.acceptSecContext(inTok, 0, 2827 inTok.length); 2829 // possibly send token to peer 2830 if (outTok != null) 2831 sendToken(outTok); 2833 // check if local context establishment is complete 2834 if (context.isEstablished()) 2835 break; 2836 } while (true); 2838 } catch (GSSException e) { 2839 print("GSS-API error: " + e.getMessage()); 2840 } 2842 6.4.6. acceptSecContext 2844 public void acceptSecContext(InputStream inStream, 2845 OutputStream outStream) throws GSSException 2847 Called by the context acceptor upon receiving a token from the peer. 2848 This call is equivalent to the byte array method. It may write an 2849 output token to the outStream, which the application will need to 2850 send to the peer for processing by its initSecContext method. 0 bytes 2851 written to the output stream indicate that no token needs to be sent 2852 to the peer. The application can call isEstablished() to determine 2853 if the context establishment phase is complete for this peer. A 2854 return value of "false" from isEstablished() indicates that more 2855 tokens are expected to be supplied to this method. 2857 Note that it is possible that acceptSecContext() return a token for 2858 the peer, and isEstablished() return "true" also. This indicates 2859 that the token needs to be sent to the peer, but the local end of the 2860 context is now fully established. 2862 The GSS-API authentication tokens contain a definitive start and end. 2863 This method will attempt to read one of these tokens per invocation, 2864 and may block on the stream if only part of the token is available. 2866 GSS-API Java Bindings December 1999 2868 Upon completion of the context establishment, the available context 2869 options may be queried through the get methods. 2871 Parameters: 2873 inStream Contains the token generated by the peer. 2875 outStream Output stream where the output token will be written. 2876 During the final stage of context establishment, there 2877 may be no bytes written. 2879 6.4.6.1. Example Code 2881 // acquire server credentials 2882 GSSCredential server = mgr.createCredential(...); 2884 // create acceptor GSS-API context fromthe default provider 2885 GSSContext context = mgr.createContext(server, null); 2887 // use standard java.io stream objects 2888 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2889 ByteArrayInputStream is = null; 2891 try { 2892 do { 2894 is = recvToken(); 2896 context.acceptSecContext(is, os); 2898 // possibly send token to peer 2899 if (os.size() > 0) 2900 sendToken(os); 2902 // check if local context establishment is complete 2903 if (context.isEstablished()) 2904 break; 2905 } while (true); 2907 } catch (GSSException e) { 2908 print("GSS-API error: " + e.getMessage()); 2909 } 2911 GSS-API Java Bindings December 1999 2913 6.4.7. isEstablished 2915 public boolean isEstablished() 2917 Used during context establishment to determine the state of the 2918 context. Returns "true" if this is a fully established context on 2919 the caller's side and no more tokens are needed from the peer. 2920 Should be called after a call to initSecContext() or 2921 acceptSecContext() when no GSSException is thrown. 2923 6.4.8. dispose 2925 public void dispose() throws GSSException 2927 Releases any system resources and cryptographic information stored in 2928 the context object. This will invalidate the context. 2930 6.4.9. getWrapSizeLimit 2932 public int getWrapSizeLimit(int qop, boolean confReq, 2933 int maxTokenSize) throws GSSException 2935 Returns the maximum message size that, if presented to the wrap 2936 method with the same confReq and qop parameters, will result in an 2937 output token containing no more than the maxTokenSize bytes. 2939 This call is intended for use by applications that communicate over 2940 protocols that impose a maximum message size. It enables the 2941 application to fragment messages prior to applying protection. 2943 GSS-API implementations are recommended but not required to detect 2944 invalid QOP values when getWrapSizeLimit is called. This routine 2945 guarantees only a maximum message size, not the availability of 2946 specific QOP values for message protection. 2948 Successful completion of this call does not guarantee that wrap will 2949 be able to protect a message of the computed length, since this 2950 ability may depend on the availability of system resources at the 2951 time that wrap is called. However, if the implementation itself 2952 imposes an upper limit on the length of messages that may be 2953 processed by wrap, the implementation should not return a value that 2954 is greater than this length. 2956 Parameters: 2958 qop Indicates the level of protection wrap will be asked 2960 GSS-API Java Bindings December 1999 2962 to provide. 2964 confReq Indicates if wrap will be asked to provide privacy 2965 service. 2967 maxTokenSize 2968 The desired maximum size of the token emitted by wrap. 2970 6.4.10. wrap 2972 public byte[] wrap(byte inBuf[], int offset, int len, 2973 MessageProp msgProp) throws GSSException 2975 Applies per-message security services over the established security 2976 context. The method will return a token with a cryptographic MIC and 2977 may optionally encrypt the specified inBuf. This method is 2978 equivalent in functionality to its stream counterpart. The returned 2979 byte array will contain both the MIC and the message. 2981 The MessageProp object is instantiated by the application and used to 2982 specify a QOP value which selects cryptographic algorithms, and a 2983 privacy service to optionally encrypt the message. The underlying 2984 mechanism that is used in the call may not be able to provide the 2985 privacy service. It sets the actual privacy service that it does 2986 provide in this MessageProp object which the caller should then query 2987 upon return. If the mechanism is not able to provide the requested 2988 QOP, it throws a GSSException with the BAD_QOP code. 2990 Since some application-level protocols may wish to use tokens emitted 2991 by wrap to provide "secure framing", implementations should support 2992 the wrapping of zero-length messages. 2994 The application will be responsible for sending the token to the 2995 peer. 2997 Parameters: 2999 inBuf Application data to be protected. 3001 offset The offset within the inBuf where the data begins. 3003 len The length of the data within the inBuf (starting at 3004 the offset). 3006 msgProp Instance of MessageProp that is used by the 3007 application to set the desired QOP and privacy state. 3008 Set the desired QOP to 0 to request the default QOP. 3010 GSS-API Java Bindings December 1999 3012 Upon return from this method, this object will contain 3013 the the actual privacy state that was applied to the 3014 message by the underlying mechanism. 3016 6.4.11. wrap 3018 public void wrap(InputStream inStream, OutputStream outStream, 3019 MessageProp msgProp) throws GSSException 3021 Allows to apply per-message security services over the established 3022 security context. The method will produce a token with a 3023 cryptographic MIC and may optionally encrypt the message in inStream. 3024 The outStream will contain both the MIC and the message. 3026 The MessageProp object is instantiated by the application and used to 3027 specify a QOP value which selects cryptographic algorithms, and a 3028 privacy service to optionally encrypt the message. The underlying 3029 mechanism that is used in the call may not be able to provide the 3030 privacy service. It sets the actual privacy service that it does 3031 provide in this MessageProp object which the caller should then query 3032 upon return. If the mechanism is not able to provide the requested 3033 QOP, it throws a GSSException with the BAD_QOP code. 3035 Since some application-level protocols may wish to use tokens emitted 3036 by wrap to provide "secure framing", implementations should support 3037 the wrapping of zero-length messages. 3039 The application will be responsible for sending the token to the 3040 peer. 3042 Parameters: 3044 inStream Input stream containing the application data to be 3045 protected. 3047 outStream The output stream to write the protected message to. 3048 The application is responsible for sending this to the 3049 other peer for processing in its unwrap method. 3051 msgProp Instance of MessageProp that is used by the 3052 application to set the desired QOP and privacy state. 3053 Set the desired QOP to 0 to request the default QOP. 3054 Upon return from this method, this object will contain 3055 the the actual privacy state that was applied to the 3056 message by the underlying mechanism. 3058 GSS-API Java Bindings December 1999 3060 6.4.12. unwrap 3062 public byte [] unwrap(byte[] inBuf, int offset, int len, 3063 MessageProp msgProp) throws GSSException 3065 Used by the peer application to process tokens generated with the 3066 wrap call. This call is equal in functionality to its stream 3067 counterpart. The method will return the message supplied in the peer 3068 application to the wrap call, verifying the embedded MIC. 3070 The MessageProp object is instantiated by the application and is used 3071 by the underlying mechanism to return information to the caller such 3072 as the QOP, whether confidentiality was applied to the message, and 3073 other supplementary message state information. 3075 Since some application-level protocols may wish to use tokens emitted 3076 by wrap to provide "secure framing", implementations should support 3077 the wrapping and unwrapping of zero-length messages. 3079 Parameters: 3081 inBuf GSS-API wrap token received from peer. 3083 offset The offset within the inBuf where the token begins. 3085 len The length of the token within the inBuf (starting at 3086 the offset). 3088 msgProp Upon return from the method, this object will contain 3089 the applied QOP, the privacy state of the message, and 3090 supplementary information described in 4.12.3 stating 3091 whether the token was a duplicate, old, out of 3092 sequence or arriving after a gap. 3094 6.4.13. unwrap 3096 public void unwrap(InputStream inStream, OutputStream outStream, 3097 MessageProp msgProp) throws GSSException 3099 Used by the peer application to process tokens generated with the 3100 wrap call. This call is equal in functionality to its byte array 3101 counterpart. It will produce the message supplied in the peer 3102 application to the wrap call, verifying the embedded MIC. 3104 The MessageProp object is instantiated by the application and is used 3105 by the underlying mechanism to return information to the caller such 3106 as the QOP, whether confidentiality was applied to the message, and 3108 GSS-API Java Bindings December 1999 3110 other supplementary message state information. 3112 Since some application-level protocols may wish to use tokens emitted 3113 by wrap to provide "secure framing", implementations should support 3114 the wrapping and unwrapping of zero-length messages. 3116 Parameters: 3118 inStream Input stream containing the GSS-API wrap token 3119 received from the peer. 3121 outStream The output stream to write the application message to. 3123 msgProp Upon return from the method, this object will contain 3124 the applied QOP, the privacy state of the message, and 3125 supplementary information described in 4.12.3 stating 3126 whether the token was a duplicate, old, out of 3127 sequence or arriving after a gap. 3129 6.4.14. getMIC 3131 public byte[] getMIC(byte []inMsg, int offset, int len, 3132 MessageProp msgProp) throws GSSException 3134 Returns a token containing a cryptographic MIC for the supplied 3135 message, for transfer to the peer application. Unlike wrap, which 3136 encapsulates the user message in the returned token, only the message 3137 MIC is returned in the output token. This method is identical in 3138 functionality to its stream counterpart. 3140 Note that privacy can only be applied through the wrap call. 3142 Since some application-level protocols may wish to use tokens emitted 3143 by getMIC to provide "secure framing", implementations should support 3144 derivation of MICs from zero-length messages. 3146 Parameters: 3148 inMsg Message to generate MIC over. 3150 offset The offset within the inMsg where the token begins. 3152 len The length of the token within the inMsg (starting at 3153 the offset). 3155 msgProp Instance of MessageProp that is used by the 3156 application to set the desired QOP. Set the desired 3158 GSS-API Java Bindings December 1999 3160 QOP to 0 in msgProp to request the default QOP. 3161 Alternatively pass in "null" for msgProp to request 3162 default QOP. 3164 6.4.15. getMIC 3166 public void getMIC(InputStream inStream, OutputStream outStream, 3167 MessageProp msgProp) throws GSSException 3169 Produces a token containing a cryptographic MIC for the supplied 3170 message, for transfer to the peer application. Unlike wrap, which 3171 encapsulates the user message in the returned token, only the message 3172 MIC is produced in the output token. This method is identical in 3173 functionality to its byte array counterpart. 3175 Note that privacy can only be applied through the wrap call. 3177 Since some application-level protocols may wish to use tokens emitted 3178 by getMIC to provide "secure framing", implementations should support 3179 derivation of MICs from zero-length messages. 3181 Parameters: 3183 inStream inStream Input stream containing the message to 3184 generate MIC over. 3186 outStream outStream Output stream to write the GSS-API output 3187 token to. 3189 msgProp Instance of MessageProp that is used by the 3190 application to set the desired QOP. Set the desired 3191 QOP to 0 in msgProp to request the default QOP. 3192 Alternatively pass in "null" for msgProp to request 3193 default QOP. 3195 6.4.16. verifyMIC 3197 public void verifyMIC(byte []inTok, int tokOffset, int tokLen, 3198 byte[] inMsg, int msgOffset, int msgLen, 3199 MessageProp msgProp) throws GSSException 3201 Verifies the cryptographic MIC, contained in the token parameter, 3202 over the supplied message. This method is equivalent in 3203 functionality to its stream counterpart. 3205 The MessageProp object is instantiated by the application and is used 3207 GSS-API Java Bindings December 1999 3209 by the underlying mechanism to return information to the caller such 3210 as the QOP indicating the strength of protection that was applied to 3211 the message and other supplementary message state information. 3213 Since some application-level protocols may wish to use tokens emitted 3214 by getMIC to provide "secure framing", implementations should support 3215 the calculation and verification of MICs over zero-length messages. 3217 Parameters: 3219 inTok Token generated by peer's getMIC method. 3221 tokOffset The offset within the inTok where the token begins. 3223 tokLen The length of the token within the inTok (starting at 3224 the offset). 3226 inMsg Application message to verify the cryptographic MIC 3227 over. 3229 msgOffset The offset within the inMsg where the message begins. 3231 msgLen The length of the message within the inMsg (starting 3232 at the offset). 3234 msgProp Upon return from the method, this object will contain 3235 the applied QOP and supplementary information 3236 described in 4.12.3 stating whether the token was a 3237 duplicate, old, out of sequence or arriving after a 3238 gap. The confidentiality state will be set to 3239 "false". 3241 6.4.17. verifyMIC 3243 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3244 MessageProp msgProp) throws GSSException 3246 Verifies the cryptographic MIC, contained in the token parameter, 3247 over the supplied message. This method is equivalent in 3248 functionality to its byte array counterpart. 3250 The MessageProp object is instantiated by the application and is used 3251 by the underlying mechanism to return information to the caller such 3252 as the QOP indicating the strength of protection that was applied to 3253 the message and other supplementary message state information. 3255 Since some application-level protocols may wish to use tokens emitted 3257 GSS-API Java Bindings December 1999 3259 by getMIC to provide "secure framing", implementations should support 3260 the calculation and verification of MICs over zero-length messages. 3262 Parameters: 3264 tokStream Input stream containing the token generated by peer's 3265 getMIC method. 3267 msgStream Input stream containing the application message to 3268 verify the cryptographic MIC over. 3270 msgProp Upon return from the method, this object will contain 3271 the applied QOP and supplementary information 3272 described in 4.12.3 stating whether the token was a 3273 duplicate, old, out of sequence or arriving after a 3274 gap. The confidentiality state will be set to 3275 "false". 3277 6.4.18. export 3279 public byte [] export() throws GSSException 3281 Provided to support the sharing of work between multiple processes. 3282 This routine will typically be used by the context-acceptor, in an 3283 application where a single process receives incoming connection 3284 requests and accepts security contexts over them, then passes the 3285 established context to one or more other processes for message 3286 exchange. 3288 This method deactivates the security context and creates an 3289 interprocess token which, when passed to the byte array constructor 3290 of the GSSContext interface in another process, will re-activate the 3291 context in the second process. Only a single instantiation of a 3292 given context may be active at any one time; a subsequent attempt by 3293 a context exporter to access the exported security context will fail. 3295 The implementation may constrain the set of processes by which the 3296 interprocess token may be imported, either as a function of local 3297 security policy, or as a result of implementation decisions. For 3298 example, some implementations may constrain contexts to be passed 3299 only between processes that run under the same account, or which are 3300 part of the same process group. 3302 The interprocess token may contain security-sensitive information 3303 (for example cryptographic keys). While mechanisms are encouraged to 3304 either avoid placing such sensitive information within interprocess 3305 tokens, or to encrypt the token before returning it to the 3307 GSS-API Java Bindings December 1999 3309 application, in a typical GSS-API implementation this may not be 3310 possible. Thus the application must take care to protect the 3311 interprocess token, and ensure that any process to which the token is 3312 transferred is trustworthy. 3314 6.4.19. requestMutualAuth 3316 public void requestMutualAuth(boolean state) throws GSSException 3318 Sets the request state of the mutual authentication flag for the 3319 context. This method is only valid before the context creation 3320 process begins and only for the initiator. 3322 Parameters: 3324 state Boolean representing if mutual authentication should 3325 be requested during context establishment. 3327 6.4.20. requestReplayDet 3329 public void requestReplayDet(boolean state) throws GSSException 3331 Sets the request state of the replay detection service for the 3332 context. This method is only valid before the context creation 3333 process begins and only for the initiator. 3335 Parameters: 3337 state Boolean representing if replay detection is desired 3338 over the established context. 3340 6.4.21. requestSequenceDet 3342 public void requestSequenceDet(boolean state) throws GSSException 3344 Sets the request state for the sequence checking service of the 3345 context. This method is only valid before the context creation 3346 process begins and only for the initiator. 3348 Parameters: 3350 state Boolean representing if sequence detection is desired 3351 over the established context. 3353 GSS-API Java Bindings December 1999 3355 6.4.22. requestCredDeleg 3357 public void requestCredDeleg(boolean state) throws GSSException 3359 Sets the request state for the credential delegation flag for the 3360 context. This method is only valid before the context creation 3361 process begins and only for the initiator. 3363 Parameters: 3365 state Boolean representing if credential delegation is 3366 desired. 3368 6.4.23. requestAnonymity 3370 public void requestAnonymity(boolean state) throws GSSException 3372 Requests anonymous support over the context. This method is only 3373 valid before the context creation process begins and only for the 3374 initiator. 3376 Parameters: 3378 state Boolean representing if anonymity support is 3379 requested. 3381 6.4.24. requestConf 3383 public void requestConf(boolean state) throws GSSException 3385 Requests that confidentiality service be available over the context. 3386 This method is only valid before the context creation process begins 3387 and only for the initiator. 3389 Parameters: 3391 state Boolean indicating if confidentiality services are to 3392 be requested for the context. 3394 6.4.25. requestInteg 3396 public void requestInteg(boolean state) throws GSSException 3398 Requests that integrity services be available over the context. This 3399 method is only valid before the context creation process begins and 3401 GSS-API Java Bindings December 1999 3403 only for the initiator. 3405 Parameters: 3407 state Boolean indicating if integrity services are to be 3408 requested for the context. 3410 6.4.26. requestLifetime 3412 public void requestLifetime(int lifetime) throws GSSException 3414 Sets the desired lifetime for the context in seconds. This method is 3415 only valid before the context creation process begins and only for 3416 the initiator. 3418 Parameters: 3420 lifetime The desired context lifetime in seconds. 3422 6.4.27. setChannelBinding 3424 public void setChannelBinding(ChannelBinding cb) throws GSSException 3426 Sets the channel bindings to be used during context establishment. 3427 This method is only valid before the context creation process begins. 3429 Parameters: 3431 cb Channel bindings to be used. 3433 6.4.28. getCredDelegState 3435 public boolean getCredDelegState() 3437 Returns the state of the delegated credentials for the context. When 3438 issued before context establishment is completed or when the 3439 isProtReady method returns "false", it returns the desired state, 3440 otherwise it will indicate the actual state over the established 3441 context. 3443 6.4.29. getMutualAuthState 3445 public boolean getMutualAuthState() 3447 GSS-API Java Bindings December 1999 3449 Returns the state of the mutual authentication option for the 3450 context. When issued before context establishment completes or when 3451 the isProtReady method returns "false", it returns the desired state, 3452 otherwise it will indicate the actual state over the established 3453 context. 3455 6.4.30. getReplayDetState 3457 public boolean getReplayDetState() 3459 Returns the state of the replay detection option for the context. 3460 When issued before context establishment completes or when the 3461 isProtReady method returns "false", it returns the desired state, 3462 otherwise it will indicate the actual state over the established 3463 context. 3465 6.4.31. getSequenceDetState 3467 public boolean getSequenceDetState() 3469 Returns the state of the sequence detection option for the context. 3470 When issued before context establishment completes or when the 3471 isProtReady method returns "false", it returns the desired state, 3472 otherwise it will indicate the actual state over the established 3473 context. 3475 6.4.32. getAnonymityState 3477 public boolean getAnonymityState() 3479 Returns "true" if this is an anonymous context. When issued before 3480 context establishment completes or when the isProtReady method 3481 returns "false", it returns the desired state, otherwise it will 3482 indicate the actual state over the established context. 3484 6.4.33. isTransferable 3486 public boolean isTransferable() throws GSSException 3488 Returns "true" if the context is transferable to other processes 3489 through the use of the export method. This call is only valid on 3490 fully established contexts. 3492 GSS-API Java Bindings December 1999 3494 6.4.34. isProtReady 3496 public boolean isProtReady() 3498 Returns "true" if the per message operations can be applied over the 3499 context. Some mechanisms may allow the usage of per-message 3500 operations before the context is fully established. This will also 3501 indicate that the get methods will return actual context state 3502 characteristics instead of the desired ones. 3504 6.4.35. getConfState 3506 public boolean getConfState() 3508 Returns the confidentiality service state over the context. When 3509 issued before context establishment completes or when the isProtReady 3510 method returns "false", it returns the desired state, otherwise it 3511 will indicate the actual state over the established context. 3513 6.4.36. getIntegState 3515 public boolean getIntegState() 3517 Returns the integrity service state over the context. When issued 3518 before context establishment completes or when the isProtReady method 3519 returns "false", it returns the desired state, otherwise it will 3520 indicate the actual state over the established context. 3522 6.4.37. getLifetime 3524 public int getLifetime() 3526 Returns the context lifetime in seconds. When issued before context 3527 establishment completes or when the isProtReady method returns 3528 "false", it returns the desired lifetime, otherwise it will indicate 3529 the remaining lifetime for the context. 3531 6.4.38. getSrcName 3533 public GSSName getSrcName() throws GSSException 3535 Returns the name of the context initiator. This call is valid only 3536 after the context is fully established or the isProtReady method 3537 returns "true". It is guaranteed to return an MN. 3539 GSS-API Java Bindings December 1999 3541 6.4.39. getTargName 3543 public GSSName getTargName() throws GSSException 3545 Returns the name of the context target (acceptor). This call is 3546 valid only after the context is fully established or the isProtReady 3547 method returns "true". It is guaranteed to return an MN. 3549 6.4.40. getMech 3551 public Oid getMech() throws GSSException 3553 Returns the mechanism oid for this context. 3555 6.4.41. getDelegCred 3557 public GSSCredential getDelegCred() throws GSSException 3559 Returns the delegated credential object on the acceptor's side. To 3560 check for availability of delegated credentials call 3561 getDelegCredState. This call is only valid on fully established 3562 contexts. 3564 6.4.42. isInitiator 3566 public boolean isInitiator() throws GSSException 3568 Returns "true" if this is the initiator of the context. This call is 3569 only valid after the context creation process has started. 3571 6.5. public class MessageProp 3573 This is a utility class used within the per-message GSSContext 3574 methods to convey per-message properties. 3576 When used with the GSSContext interface's wrap and getMIC methods, an 3577 instance of this class is used to indicate the desired QOP and to 3578 request if confidentiality services are to be applied to caller 3579 supplied data (wrap only). To request default QOP, the value of 0 3580 should be used for QOP. 3582 When used with the unwrap and verifyMIC methods of the GSSContext 3583 interface, an instance of this class will be used to indicate the 3585 GSS-API Java Bindings December 1999 3587 applied QOP and confidentiality services over the supplied message. 3588 In the case of verifyMIC, the confidentiality state will always be 3589 "false". Upon return from these methods, this object will also 3590 contain any supplementary status values applicable to the processed 3591 token. The supplementary status values can indicate old tokens, out 3592 of sequence tokens, gap tokens or duplicate tokens. 3594 6.5.1. Constructors 3596 public MessageProp(boolean privState) 3598 Constructor which sets QOP to 0 indicating that the default QOP is 3599 requested. 3601 Parameters: 3603 privState The desired privacy state. "true" for privacy and 3604 "false" for integrity only. 3606 public MessageProp(int qop, boolean privState) 3608 Constructor which sets the values for the qop and privacy state. 3610 Parameters: 3612 qop The desired QOP. Use 0 to request a default QOP. 3614 privState The desired privacy state. "true" for privacy and 3615 "false" for integrity only. 3617 6.5.2. getQOP 3619 public int getQOP() 3621 Retrieves the QOP value. 3623 6.5.3. getPrivacy 3625 public boolean getPrivacy() 3627 Retrieves the privacy state. 3629 GSS-API Java Bindings December 1999 3631 6.5.4. getMinorStatus 3633 public int getMinorStatus() 3635 Retrieves the minor status that the underlying mechanism might have 3636 set. 3638 6.5.5. getMinorString 3640 public String getMinorString() 3642 Returns a string explaining the mechanism specific error code. null 3643 will be returned when no mechanism error code has been set. 3645 6.5.6. setQOP 3647 public void setQOP(int qopVal) 3649 Sets the QOP value. 3651 Parameters: 3653 qopVal The QOP value to be set. Use 0 to request a default 3654 QOP value. 3656 6.5.7. setPrivacy 3658 public void setPrivacy(boolean privState) 3660 Sets the privacy state. 3662 Parameters: 3664 privState The privacy state to set. 3666 6.5.8. isDuplicateToken 3668 public boolean isDuplicateToken() 3670 Returns "true" if this is a duplicate of an earlier token. 3672 GSS-API Java Bindings December 1999 3674 6.5.9. isOldToken 3676 public boolean isOldToken() 3678 Returns "true" if the token's validity period has expired. 3680 6.5.10. isUnseqToken 3682 public boolean isUnseqToken() 3684 Returns "true" if a later token has already been processed. 3686 6.5.11. isGapToken 3688 public boolean isGapToken() 3690 Returns "true" if an expected per-message token was not received. 3692 6.5.12. setSupplementaryStates 3694 public void setSupplementaryStates(boolean duplicate, 3695 boolean old, boolean unseq, boolean gap, 3696 int minorStatus, String minorString) 3698 This method sets the state for the supplementary information flags 3699 and the minor status in MessageProp. It is not used by the 3700 application but by the GSS implementation to return this information 3701 to the caller of a per-message context method. 3703 Parameters: 3705 duplicate true if the token was a duplicate of an earlier token, 3706 false otherwise 3708 old true if the token's validity period has expired, false 3709 otherwise 3711 unseq true if a later token has already been processed, 3712 false otherwise 3714 gap true if one or more predecessor tokens have not yet 3715 been successfully processed, false otherwise 3717 minorStatus the integer minor status code that the underlying 3718 mechanism wants to set 3720 GSS-API Java Bindings December 1999 3722 minorString the textual representation of the minorStatus 3723 value 3725 6.6. public class ChannelBinding 3727 The GSS-API accommodates the concept of caller-provided channel 3728 binding information. Channel bindings are used to strengthen the 3729 quality with which peer entity authentication is provided during 3730 context establishment. They enable the GSS-API callers to bind the 3731 establishment of the security context to relevant characteristics 3732 like addresses or to application specific data. 3734 The caller initiating the security context must determine the 3735 appropriate channel binding values to set in the GSSContext object. 3736 The acceptor must provide an identical binding in order to validate 3737 that received tokens possess correct channel-related characteristics. 3739 Use of channel bindings is optional in GSS-API. Since channel- 3740 binding information may be transmitted in context establishment 3741 tokens, applications should therefore not use confidential data as 3742 channel-binding components. 3744 6.6.1. Constructors 3746 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3747 byte[] appData) 3749 Create a ChannelBinding object with user supplied address information 3750 and data. "null" values can be used for any fields which the 3751 application does not want to specify. 3753 Parameters: 3755 initAddr The address of the context initiator. "null" value 3756 can be supplied to indicate that the application does 3757 not want to set this value. 3759 acceptAddrThe address of the context acceptor. "null" value can 3760 be supplied to indicate that the application does not 3761 want to set this value. 3763 appData Application supplied data to be used as part of the 3764 channel bindings. "null" value can be supplied to 3765 indicate that the application does not want to set 3767 GSS-API Java Bindings December 1999 3769 this value. 3771 public ChannelBinding(byte[] appData) 3773 Creates a ChannelBinding object without any addressing information. 3775 Parameters: 3777 appData Application supplied data to be used as part of the 3778 channel bindings. 3780 6.6.2. getInitiatorAddress 3782 public InetAddress getInitiatorAddress() 3784 Returns the initiator's address for this channel binding. "null" is 3785 returned if the address has not been set. 3787 6.6.3. getAcceptorAddress 3789 public InetAddress getAcceptorAddress() 3791 Returns the acceptor's address for this channel binding. "null" is 3792 returned if the address has not been set. 3794 6.6.4. getApplicationData 3796 public byte[] getApplicationData() 3798 Returns application data being used as part of the ChannelBinding. 3799 "null" is returned if no application data has been specified for the 3800 channel binding. 3802 6.6.5. equals 3804 public boolean equals(Object obj) 3806 Returns "true" if two channel bindings match. (Note that the Java 3807 language specification requires that two objects that are equal 3808 according to the equals(Object) method must return the same integer 3809 result when the hashCode() method is called on them.) 3811 GSS-API Java Bindings December 1999 3813 Parameters: 3815 obj Another channel binding to compare with. 3817 6.7. public class Oid 3819 This class represents Universal Object Identifiers (Oids) and their 3820 associated operations. 3822 Oids are hierarchically globally-interpretable identifiers used 3823 within the GSS-API framework to identify mechanisms and name formats. 3825 The structure and encoding of Oids is defined in ISOIEC-8824 and 3826 ISOIEC-8825. For example the Oid representation of Kerberos V5 3827 mechanism is "1.2.840.113554.1.2.2" 3829 The GSSName name class contains public static Oid objects 3830 representing the standard name types defined in GSS-API. 3832 6.7.1. Constructors 3834 public Oid(String strOid) throws GSSException 3836 Creates an Oid object from a string representation of its integer 3837 components (e.g. "1.2.840.113554.1.2.2"). 3839 Parameters: 3841 strOid The string representation for the oid. 3843 public Oid(InputStream derOid) throws GSSException 3845 Creates an Oid object from its DER encoding. This refers to the full 3846 encoding including tag and length. The structure and encoding of 3847 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3848 identical in functionality to its byte array counterpart. 3850 Parameters: 3852 derOid Stream containing the DER encoded oid. 3854 public Oid(byte[] DEROid) throws GSSException 3856 GSS-API Java Bindings December 1999 3858 Creates an Oid object from its DER encoding. This refers to the full 3859 encoding including tag and length. The structure and encoding of 3860 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3861 identical in functionality to its byte array counterpart. 3863 Parameters: 3865 derOid Byte array storing a DER encoded oid. 3867 6.7.2. toString 3869 public String toString() 3871 Returns a string representation of the oid's integer components in 3872 dot separated notation (e.g. "1.2.840.113554.1.2.2"). 3874 6.7.3. equals 3876 public boolean equals(Object Obj) 3878 Returns "true" if the two Oid objects represent the same oid value. 3879 (Note that the Java language specification requires that two objects 3880 that are equal according to the equals(Object) method must return the 3881 same integer result when the hashCode() method is called on them.) 3883 Parameters: 3885 obj Another Oid object to compare with. 3887 6.7.4. getDER 3889 public byte[] getDER() 3891 Returns the full ASN.1 DER encoding for this oid object, which 3892 includes the tag and length. 3894 6.7.5. containedIn 3896 public boolean containedIn(Oid[] oids) 3898 A utility method to test if an Oid object is contained within the 3899 supplied Oid object array. 3901 Parameters: 3903 GSS-API Java Bindings December 1999 3905 oids An array of oids to search. 3907 6.8. public class GSSException extends Exception 3909 This exception is thrown whenever a fatal GSS-API error occurs 3910 including mechanism specific errors. It may contain both, the major 3911 and minor, GSS-API status codes. The mechanism implementers are 3912 responsible for setting appropriate minor status codes when throwing 3913 this exception. Aside from delivering the numeric error code(s) to 3914 the caller, this class performs the mapping from their numeric values 3915 to textual representations. All Java GSS-API methods are declared 3916 throwing this exception. 3918 All implementations are encouraged to use the Java 3919 internationalization techniques to provide local translations of the 3920 message strings. 3922 6.8.1. Static Constants 3924 All valid major GSS-API error code values are declared as constants 3925 in this class. 3927 public static final int BAD_BINDINGS 3929 Channel bindings mismatch error. 3931 public static final int BAD_MECH 3933 Unsupported mechanism requested error. 3935 public static final int BAD_NAME 3937 Invalid name provided error. 3939 public static final int BAD_NAMETYPE 3941 Name of unsupported type provided error. 3943 public static final int BAD_STATUS 3945 GSS-API Java Bindings December 1999 3947 Invalid status code error - this is the default status value. 3949 public static final int BAD_MIC 3951 Token had invalid integrity check error. 3953 public static final int CONTEXT_EXPIRED 3955 Specified security context expired error. 3957 public static final int CREDENTIALS_EXPIRED 3959 Expired credentials detected error. 3961 public static final int DEFECTIVE_CREDENTIAL 3963 Defective credential error. 3965 public static final int DEFECTIVE_TOKEN 3967 Defective token error. 3969 public static final int FAILURE 3971 General failure, unspecified at GSS-API level. 3973 public static final int NO_CONTEXT 3975 Invalid security context error. 3977 public static final int NO_CRED 3979 Invalid credentials error. 3981 public static final int BAD_QOP 3983 Unsupported QOP value error. 3985 GSS-API Java Bindings December 1999 3987 public static final int UNAUTHORIZED 3989 Operation unauthorized error. 3991 public static final int UNAVAILABLE 3993 Operation unavailable error. 3995 public static final int DUPLICATE_ELEMENT 3997 Duplicate credential element requested error. 3999 public static final int NAME_NOT_MN 4001 Name contains multi-mechanism elements error. 4003 public static final int DUPLICATE_TOKEN 4005 The token was a duplicate of an earlier token. This is a fatal error 4006 code that may occur during context establishment. It is not used to 4007 indicate supplementary status values. The MessageProp object is used 4008 for that purpose. 4010 public static final int OLD_TOKEN 4012 The token's validity period has expired. This is a fatal error code 4013 that may occur during context establishment. It is not used to 4014 indicate supplementary status values. The MessageProp object is used 4015 for that purpose. 4017 public static final int UNSEQ_TOKEN 4019 A later token has already been processed. This is a fatal error code 4020 that may occur during context establishment. It is not used to 4021 indicate supplementary status values. The MessageProp object is used 4022 for that purpose. 4024 public static final int GAP_TOKEN 4026 An expected per-message token was not received. This is a fatal 4027 error code that may occur during context establishment. It is not 4029 GSS-API Java Bindings December 1999 4031 used to indicate supplementary status values. The MessageProp object 4032 is used for that purpose. 4034 6.8.2. Constructors 4036 public GSSException(int majorCode) 4038 Creates a GSSException object with a specified major code. 4040 Parameters: 4042 majorCode The GSS error code causing this exception to be 4043 thrown. 4045 public GSSException(int majorCode, int minorCode, String minorString) 4047 Creates a GSSException object with the specified major code, minor 4048 code, and minor code textual explanation. This constructor is to be 4049 used when the exception is originating from the security mechanism. 4050 It allows to specify the GSS code and the mechanism code. 4052 Parameters: 4054 majorCode The GSS error code causing this exception to be 4055 thrown. 4057 minorCode The mechanism error code causing this exception 4058 to be thrown. 4060 minorString The textual explanation of the mechanism error 4061 code. 4063 6.8.3. getMajor 4065 public int getMajor() 4067 Returns the major code representing the GSS error code that caused 4068 this exception to be thrown. 4070 6.8.4. getMinor 4072 public int getMinor() 4074 Returns the mechanism error code that caused this exception. The 4076 GSS-API Java Bindings December 1999 4078 minor code is set by the underlying mechanism. Value of 0 indicates 4079 that mechanism error code is not set. 4081 6.8.5. getMajorString 4083 public String getMajorString() 4085 Returns a string explaining the GSS major error code causing this 4086 exception to be thrown. 4088 6.8.6. getMinorString 4090 public String getMinorString() 4092 Returns a string explaining the mechanism specific error code. null 4093 will be returned when no mechanism error code has been set. 4095 6.8.7. setMinor 4097 public void setMinor(int minorCode, String message) 4099 Used internally by the GSS-API implementation and the underlying 4100 mechanisms to set the minor code and its textual representation. 4102 Parameters: 4104 minorCode The mechanism specific error code. 4106 message A textual explanation of the mechanism error code. 4108 6.8.8. toString 4110 public String toString() 4112 Returns a textual representation of both the major and minor status 4113 codes. 4115 6.8.9. getMessage 4117 public String getMessage() 4119 Returns a detailed message of this exception. Overrides 4120 Throwable.getMessage. It is customary in Java to use this method to 4122 GSS-API Java Bindings December 1999 4124 obtain exception information. 4126 7. Sample Applications 4128 Full Copyright Statement 4130 Copyright (C) The Internet Society (1999). All Rights Reserved. 4132 This document and translations of it may be copied and furnished 4133 to others, and derivative works that comment on or otherwise explain 4134 it or assist in its implementation may be prepared, copied, published 4135 and distributed, in whole or in part, without restriction of any 4136 kind, provided that the above copyright notice and this paragraph are 4137 included on all such copies and derivative works. However, this 4138 document itself may not be modified in any way, such as by removing 4139 the copyright notice or references to the Internet Society or other 4140 Internet organizations, except as needed for the purpose of 4141 developing Internet standards in which case the procedures for 4142 copyrights defined in the Internet Standards process must be 4143 followed, or as required to translate it into languages other than 4144 English. 4146 The limited permissions granted above are perpetual and will not 4147 be revoked by the Internet Society or its successors or assigns. 4149 This document and the information contained herein is provided on 4150 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 4151 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 4152 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 4153 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4154 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4156 7.1. Simple GSS Context Initiator 4158 import org.ietf.jgss.*; 4160 /** 4161 * This is a partial sketch for a simple client program that acts 4162 * as a GSS context initiator. It illustrates how to use the Java 4163 * bindings for the GSS-API specified in 4164 * draft-ietf-cat-gssv2-javabind-04.txt. 4165 * 4166 * This code sketch assumes the existence of a GSS-API 4168 GSS-API Java Bindings December 1999 4170 * implementation that supports the mechanism that it will need and 4171 * is present as a library package (org.ietf.jgss) either as part of 4172 * the standard JRE or in the CLASSPATH the application specifies. 4173 */ 4175 public class SimpleClient { 4177 private String serviceName; // name of peer (ie. server) 4178 private GSSCredential clientCred = null; 4179 private GSSContext context = null; 4180 private Oid mech; // underlying mechanism to use 4182 private GSSManager mgr = GSSManager.getInstance(); 4184 ... 4185 ... 4187 private void clientActions() { 4189 initializeGSS(); 4190 establishContext(); 4191 doCommunication(); 4192 } 4194 /** 4195 * Acquire credentials for the client. 4196 */ 4197 private void initializeGSS() { 4199 try { 4201 clientCred = mgr.createCredential(null /*default princ*/, 4202 GSSCredential.INDEFINITE /* max lifetime */, 4203 mech /* mechanism to use */, 4204 GSSCredential.INITIATE_ONLY /* init context */); 4206 print("GSSCredential created for " + 4207 cred.getName().toString()); 4208 print("Credential lifetime (sec)=" + 4209 cred.getRemainingLifetime()); 4210 } catch (GSSException e) { 4211 print("GSS-API error in credential acquisition: " 4212 + e.getMessage()); 4213 ... 4214 ... 4215 } 4217 ... 4219 GSS-API Java Bindings December 1999 4221 ... 4222 } 4224 /** 4225 * Does the security context establishment with the 4226 * server. 4227 */ 4228 private void establishContext() { 4230 byte[] inToken = new byte[0]; 4231 byte[] outToken = null; 4233 try { 4235 GSSName peer = mgr.createName(serviceName, 4236 GSSName.NT_HOSTBASED_SERVICE); 4238 context = mgr.createContext(peer, mech, gssCred, 4239 GSSContext.INDEFINITE/*lifetime*/); 4241 // Will need to support confidentiality 4242 context.requestConf(true); 4244 while (!context.isEstablished()) { 4246 outToken = context.initSecContext(inToken, 0, 4247 inToken.length); 4249 if (outToken != null) 4250 writeGSSToken(outToken); 4252 if (!context.isEstablished()) 4253 inToken = readGSSToken(); 4254 } 4256 GSSName peer = context.getSrcName(); 4257 print("Security context established with " + peer + 4258 " using underlying mechanism " + mech.toString()); 4259 } catch (GSSException e) { 4260 print("GSS-API error during context establishment: " 4261 + e.getMessage()); 4262 ... 4263 ... 4264 } 4266 ... 4267 ... 4268 } 4270 GSS-API Java Bindings December 1999 4272 /** 4273 * Sends some data to the server and reads back the 4274 * response. 4275 */ 4276 private void doCommunication() { 4277 byte[] inToken = null; 4278 byte[] outToken = null; 4279 byte[] buffer; 4281 // Container for multiple input-output arguments to and 4282 // from the per-message routines (e.g., wrap/unwrap). 4283 MessageProp messgInfo = new MessageProp(); 4285 try { 4287 /* 4288 * Now send some bytes to the server to be 4289 * processed. They will be integrity protected but 4290 * not encrypted for privacy. 4291 */ 4293 buffer = readFromFile(); 4295 // Set privacy to false and use the default QOP 4296 messgInfo.setPrivacy(false); 4298 outToken = context.wrap(buffer, 0, buffer.length, 4299 messgInfo); 4301 writeGSSToken(outToken); 4303 /* 4304 * Now read the response from the server. 4305 */ 4307 inToken = readGSSToken(); 4308 buffer = context.unwrap(inToken, 0, inToken.length, 4309 messgInfo); 4310 // All ok if no exception was thrown! 4312 GSSName peer = context.getSrcName(); 4314 print("Message from " + peer.toString() 4315 + " arrived."); 4316 print("Was it encrypted? " + 4317 messgInfo.getPrivacy()); 4318 print("Duplicate Token? " + 4319 messgInfo.isDuplicateToken()); 4321 GSS-API Java Bindings December 1999 4323 print("Old Token? " + 4324 messgInfo.isOldToken()); 4325 print("Unsequenced Token? " + 4326 messgInfo.isUnseqToken()); 4327 print("Gap Token? " + 4328 messgInfo.isGapToken()); 4330 ... 4331 ... 4333 } catch (GSSException e) { 4334 print("GSS-API error in per-message calls: " 4335 + e.getMessage()); 4336 ... 4337 ... 4338 } 4340 ... 4341 ... 4343 } // end of doCommunication method 4345 ... 4346 ... 4348 } // end of class SimpleClient 4350 7.2. Simple GSS Context Acceptor 4352 import org.ietf.jgss.*; 4354 /** 4355 * This is a partial sketch for a simple server program that acts 4356 * as a GSS context acceptor. It illustrates how to use the Java 4357 * bindings for the GSS-API specified in 4358 * draft-ietf-cat-gssv2-javabind-04.txt. 4359 * 4360 * This code sketch assumes the existence of a GSS-API 4361 * implementation that supports the mechanisms that it will need and 4362 * is present as a library package (org.ietf.jgss) either as part of 4363 * the standard JRE or in the CLASSPATH the application specifies. 4364 */ 4366 GSS-API Java Bindings December 1999 4368 import org.ietf.jgss.*; 4370 public class SimpleServer { 4372 private String serviceName; 4373 private GSSName name; 4374 private GSSCredential cred; 4376 private GSSManager mgr; 4378 ... 4379 ... 4381 /** 4382 * Wait for client connections, establish security contexts and 4383 * provide service. 4384 */ 4385 private void loop() { 4387 ... 4388 ... 4390 mgr = GSSManager.getInstance(); 4392 name = mgr.createName(serviceName, 4393 GSSName.NT_HOSTBASED_SERVICE); 4395 cred = mgr.createCredential(name, 4396 GSSCredential.INDEFINITE, 4397 null, 4398 GSSCredential.ACCEPT_ONLY); 4400 // Loop infinitely 4401 while (true) { 4403 Socket s = serverSock.acceptSecContext(); 4405 // Start a new thread to serve this connection 4406 Thread serverThread = new ServerThread(s); 4407 serverThread.start(); 4409 } 4410 } 4412 /** 4413 * Inner class ServerThread whose run() method provides the 4414 * secure service to a connection. 4416 GSS-API Java Bindings December 1999 4418 */ 4420 private class ServerThread extends Thread { 4422 ... 4423 ... 4425 /** 4426 * Deals with the connection from one client. It also 4427 * handles all GSSException's thrown while talking to 4428 * this client. 4429 */ 4430 public void run() { 4432 byte[] inToken = null; 4433 byte[] outToken = null; 4434 byte[] buffer; 4436 GSSName peer; 4438 // Container for multiple input-output arguments to and 4439 // from the per-message routines (ie. wrap/unwrap). 4440 MessageProp supplInfo = new MessageProp(); 4442 GSSContext secContext = null; 4444 try { 4446 // Now do the context establishment loop 4448 GSSContext context = mgr.createContext(cred); 4450 while (!context.isEstablished()) { 4452 inToken = readGSSToken(); 4454 outToken = context.acceptSecContext(inToken, 0, 4455 inToken.length); 4457 if (outToken != null) 4458 writeGSSToken(outToken); 4460 } 4462 // SimpleServer wants confidentiality to be 4463 // available. Check for it. 4465 GSS-API Java Bindings December 1999 4467 if (!context.getConfState()){ 4468 ... 4469 ... 4470 } 4472 GSSName peer = context.getSrcName(); 4473 Oid mech = context.getMech(); 4474 print("Security context established with " + 4475 peer.toString() + 4476 " using underlying mechanism " + 4477 mech.toString() + 4478 " from Provider " + 4479 context.getProvider().getName()); 4481 // Now read the bytes sent by the client to be 4482 // processed. 4483 inToken = readGSSToken(); 4485 // Unwrap the message 4486 buffer = context.unwrap(inToken, 0, inToken.length, 4487 supplInfo); 4488 // All ok if no exception was thrown! 4490 // Print other supplementary per-message status 4491 // information 4493 print("Message from " + 4494 peer.toString() + " arrived."); 4495 print("Was it encrypted? " + 4496 supplInfo.getPrivacy()); 4497 print("Duplicate Token? " + 4498 supplInfo.isDuplicateToken()); 4499 print("Old Token? " + supplInfo.isOldToken()); 4500 print("Unsequenced Token? " + 4501 supplInfo.isUnseqToken()); 4502 print("Gap Token? " + supplInfo.isGapToken()); 4504 /* 4505 * Now process the bytes and send back an encrypted 4506 * response. 4507 */ 4509 buffer = serverProcess(buffer); 4511 // Encipher it and send it across 4513 supplInfo.setPrivacy(true); // privacy requested 4515 GSS-API Java Bindings December 1999 4517 supplInfo.setQOP(0); // default QOP 4518 outToken = context.wrap(buffer, 0, buffer.length, 4519 supplInfo); 4520 writeGSSToken(outToken); 4522 } catch (GSSException e) { 4523 print("GSS-API Error: " + e.getMessage()); 4524 // Alternatively, could call e.getMajorMessage() 4525 // and e.getMinorMessage() 4526 print("Abandoning security context."); 4528 ... 4529 ... 4531 } 4533 ... 4534 ... 4536 } // end of run method in ServerThread 4538 } // end of inner class ServerThread 4540 ... 4541 ... 4543 } // end of class SimpleServer 4545 8. Security Considerations 4547 The Java language security model allows platform providers to have 4548 policy based fine-grained access control over any resource that an 4549 application wants. When using a Java security manager (such as, but 4550 not limited to, the the case of applets running in browsers) the 4551 application code is in a sandbox by default. 4553 Administrators of the platform JRE determine what permissions, if 4554 any, are to be given to source from different codebases. Thus the 4555 administrator has to be aware of any special requirements that the 4556 GSS provider might have for system resources. For instance, a 4557 Kerberos provider might wish to make a network connection to the KDC 4558 to obtain initial credentials. This would not be allowed under the 4559 sandbox unless the administrator had granted permissions for this. 4560 Also note that this granting and checking of permissions happens 4561 transparently to the application and is outside the scope of this 4563 GSS-API Java Bindings December 1999 4565 draft. 4567 The Java language allows admininstrators to pre-configure a list of 4568 security service providers in the /lib/security/java.security 4569 file. At runtime, the system approaches these providers in order of 4570 preference when looking for security related services. Applications 4571 have a means to modify this list through methods in the "Security" 4572 class in the "java.security" package. However, since these 4573 modifications would be visible in the entire JVM and thus affect all 4574 code executing in it, this operation is not available in the sandbox 4575 and requires special permissions to perform. Thus when a GSS 4576 application has special needs that are met by a particular security 4577 provider, it has two choices: 4579 1) To install the provider on a JVM wide basis using the 4580 java.security.Security class and then depend on the system 4581 to find the right provider automatically when the need 4582 arises. (This would require the application to be granted a 4583 "insertProvider SecurityPermission".) 4585 2) To pass an instance of the provider to the local instance 4586 of GSSManager so that only factory calls going through that 4587 GSSManager use the desired provider. (This would not 4588 require any permissions.) 4590 9. Acknowledgments 4592 This proposed API leverages earlier work performed by the IETF's CAT 4593 WG as outlined in both RFC 2078 and J. Wray's C-bindings draft for 4594 the GSS-API. Many conceptual definitions, implementation directions, 4595 and explanations have been included from the C-bindings draft. 4597 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4598 Saltz and other members of Sun's development team for their helpful 4599 input, comments and suggestions. 4601 We would also like to thank Joe Salowey, and Michael Smith for many 4602 insightful ideas and suggestions that have contributed to this draft. 4604 GSS-API Java Bindings December 1999 4606 10. Bibliography 4608 [GSSAPIv2] 4609 J. Linn, "Generic Security Service Application Program Interface, 4610 Version 2", RFC 2078, January 1997. 4612 [GSSAPIv2-UPDATE] 4613 J. Linn, "Generic Security Service Application Program Interface, 4614 Version 2, Update 1", IETF work in progress, Internet Draft, July 4615 1998. 4617 [GSSAPI-Cbind] 4618 J. Wray, "Generic Security Service API Version 2 : C-bindings", IETF 4619 work in progress, Internet Draft, July 1998. 4621 [KERBEROS_V5] 4622 J. Linn, "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, June 4623 1996. 4625 [SPKM] 4626 C. Adams, "The Simple Public-Key GSS-API Mechanism", RFC 2025, 4627 October 1996. 4629 GSS-API Java Bindings December 1999 4631 11. Author's Address 4633 Address comments related to this memorandum to: 4635 4637 Jack Kabat 4638 ValiCert, Inc. 4639 1215 Terra Bella Avenue 4640 Mountain View, CA 4641 94043, USA 4643 Phone: +1-650-567-5496 4644 E-mail: jackk@valicert.com 4646 Mayank Upadhyay 4647 Sun Microsystems, Inc. 4648 901 San Antonio Road, MS CUP02-102 4649 Palo Alto, CA 94303 4651 Phone: +1-408-517-5956 4652 E-mail: mdu@eng.sun.com