idnits 2.17.1 draft-ietf-cat-gssv2-javabind-03.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 96 pages Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** 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 305 has weird spacing: '...ment of a sec...' == Line 384 has weird spacing: '...rmation to en...' == Line 1241 has weird spacing: '...ith the major...' == Line 3040 has weird spacing: '...nStream inStr...' == Line 3574 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 (October 1999) is 8960 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 4412 looks like a reference -- Missing reference section? 'SPKM' on line 4429 looks like a reference -- Missing reference section? 'KERBV5' on line 44 looks like a reference -- Missing reference section? 'GSSAPI-C' on line 245 looks like a reference -- Missing reference section? '0' on line 4078 looks like a reference -- Missing reference section? 'GSSAPIv2-UPDATE' on line 4416 looks like a reference -- Missing reference section? 'GSSAPI-Cbind' on line 4421 looks like a reference Summary: 5 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 October 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 October 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 class GSSManager . . . . . . . . . . . . . . . . 32 91 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . . 33 92 6.1.2. Constructors . . . . . . . . . . . . . . . . . . . . . 33 93 6.1.3. setProvider . . . . . . . . . . . . . . . . . . . . . 34 94 6.1.4. setProvider . . . . . . . . . . . . . . . . . . . . . 34 95 6.1.5. getProvider . . . . . . . . . . . . . . . . . . . . . 35 97 GSS-API Java Bindings October 1999 99 6.1.6. getMechs . . . . . . . . . . . . . . . . . . . . . . . 35 100 6.1.7. getNamesForMech . . . . . . . . . . . . . . . . . . . 35 101 6.1.8. getMechsForName . . . . . . . . . . . . . . . . . . . 36 102 6.1.9. createName . . . . . . . . . . . . . . . . . . . . . . 36 103 6.1.10. createName . . . . . . . . . . . . . . . . . . . . . 36 104 6.1.11. createName . . . . . . . . . . . . . . . . . . . . . 37 105 6.1.12. createName . . . . . . . . . . . . . . . . . . . . . 38 106 6.1.13. createCredential . . . . . . . . . . . . . . . . . . 38 107 6.1.14. createCredential . . . . . . . . . . . . . . . . . . 38 108 6.1.15. createCredential . . . . . . . . . . . . . . . . . . 39 109 6.1.16. createContext . . . . . . . . . . . . . . . . . . . . 40 110 6.1.17. createContext . . . . . . . . . . . . . . . . . . . . 40 111 6.1.18. createContext . . . . . . . . . . . . . . . . . . . . 41 112 6.2. public interface GSSName . . . . . . . . . . . . . . . . 41 113 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . . 41 114 6.2.2. Static Constants . . . . . . . . . . . . . . . . . . . 42 115 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 43 116 6.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 43 117 6.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . . 44 118 6.2.6. export . . . . . . . . . . . . . . . . . . . . . . . . 44 119 6.2.7. toString . . . . . . . . . . . . . . . . . . . . . . . 44 120 6.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 44 121 6.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 45 122 6.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . 45 123 6.3. public interface GSSCredential implements Cloneable . . 45 124 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . . 46 125 6.3.2. Static Constants . . . . . . . . . . . . . . . . . . . 47 126 6.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 47 127 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 47 128 6.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 47 129 6.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . . 48 130 6.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . . 48 131 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . . 48 132 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . . 49 133 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 49 134 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 49 135 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 49 136 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 50 137 6.4. public interface GSSContext . . . . . . . . . . . . . . 51 138 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . . 52 139 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . . 53 140 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . . 54 141 6.4.3.1. Example Code . . . . . . . . . . . . . . . . . . . . 54 142 6.4.4. initSecContext . . . . . . . . . . . . . . . . . . . . 55 143 6.4.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 56 144 6.4.5. acceptSecContext . . . . . . . . . . . . . . . . . . . 57 145 6.4.5.1. Example Code . . . . . . . . . . . . . . . . . . . . 57 146 6.4.6. acceptSecContext . . . . . . . . . . . . . . . . . . . 58 148 GSS-API Java Bindings October 1999 150 6.4.6.1. Example Code . . . . . . . . . . . . . . . . . . . . 59 151 6.4.7. isEstablished . . . . . . . . . . . . . . . . . . . . 59 152 6.4.8. dispose . . . . . . . . . . . . . . . . . . . . . . . 60 153 6.4.9. getWrapSizeLimit . . . . . . . . . . . . . . . . . . . 60 154 6.4.10. wrap . . . . . . . . . . . . . . . . . . . . . . . . 61 155 6.4.11. wrap . . . . . . . . . . . . . . . . . . . . . . . . 61 156 6.4.12. unwrap . . . . . . . . . . . . . . . . . . . . . . . 62 157 6.4.13. unwrap . . . . . . . . . . . . . . . . . . . . . . . 63 158 6.4.14. getMIC . . . . . . . . . . . . . . . . . . . . . . . 64 159 6.4.15. getMIC . . . . . . . . . . . . . . . . . . . . . . . 64 160 6.4.16. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 65 161 6.4.17. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 66 162 6.4.18. export . . . . . . . . . . . . . . . . . . . . . . . 67 163 6.4.19. requestMutualAuth . . . . . . . . . . . . . . . . . . 67 164 6.4.20. requestReplayDet . . . . . . . . . . . . . . . . . . 68 165 6.4.21. requestSequenceDet . . . . . . . . . . . . . . . . . 68 166 6.4.22. requestCredDeleg . . . . . . . . . . . . . . . . . . 68 167 6.4.23. requestAnonymity . . . . . . . . . . . . . . . . . . 69 168 6.4.24. requestConf . . . . . . . . . . . . . . . . . . . . . 69 169 6.4.25. requestInteg . . . . . . . . . . . . . . . . . . . . 69 170 6.4.26. requestLifetime . . . . . . . . . . . . . . . . . . . 69 171 6.4.27. setChannelBinding . . . . . . . . . . . . . . . . . . 70 172 6.4.28. getCredDelegState . . . . . . . . . . . . . . . . . . 70 173 6.4.29. getMutualAuthState . . . . . . . . . . . . . . . . . 70 174 6.4.30. getReplayDetState . . . . . . . . . . . . . . . . . . 70 175 6.4.31. getSequenceDetState . . . . . . . . . . . . . . . . . 71 176 6.4.32. getAnonymityState . . . . . . . . . . . . . . . . . . 71 177 6.4.33. isTransferable . . . . . . . . . . . . . . . . . . . 71 178 6.4.34. isProtReady . . . . . . . . . . . . . . . . . . . . . 71 179 6.4.35. getConfState . . . . . . . . . . . . . . . . . . . . 71 180 6.4.36. getIntegState . . . . . . . . . . . . . . . . . . . . 72 181 6.4.37. getLifetime . . . . . . . . . . . . . . . . . . . . . 72 182 6.4.38. getSrcName . . . . . . . . . . . . . . . . . . . . . 72 183 6.4.39. getTargName . . . . . . . . . . . . . . . . . . . . . 72 184 6.4.40. getMech . . . . . . . . . . . . . . . . . . . . . . . 72 185 6.4.41. getDelegCred . . . . . . . . . . . . . . . . . . . . 73 186 6.4.42. isInitiator . . . . . . . . . . . . . . . . . . . . . 73 187 6.5. public class MessageProp . . . . . . . . . . . . . . . . 73 188 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . . 73 189 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . . 74 190 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . . 74 191 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . . 74 192 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . . 74 193 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . . 75 194 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . . 75 195 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . . 75 196 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . . 75 197 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 75 199 GSS-API Java Bindings October 1999 201 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 75 202 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 76 203 6.6. public class ChannelBinding . . . . . . . . . . . . . . 76 204 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . . 77 205 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 77 206 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . . 78 207 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . . 78 208 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 78 209 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 78 210 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . . 79 211 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . . 79 212 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . . 80 213 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . . 80 214 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 80 215 6.8. public class GSSException extends Exception . . . . . . 80 216 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . . 81 217 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . . 83 218 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . . 84 219 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . . 84 220 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . . 84 221 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . . 84 222 6.8.7. setMinor . . . . . . . . . . . . . . . . . . . . . . . 85 223 6.8.8. toString . . . . . . . . . . . . . . . . . . . . . . . 85 224 6.8.9. getMessage . . . . . . . . . . . . . . . . . . . . . . 85 225 7. Sample Applications . . . . . . . . . . . . . . . . . . . 85 226 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 86 227 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . 90 228 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 94 229 9. Bibliography . . . . . . . . . . . . . . . . . . . . . . . 95 230 10. Author's Address . . . . . . . . . . . . . . . . . . . . 96 232 GSS-API Java Bindings October 1999 234 1. Introduction 236 This document specifies Java language bindings for the Generic 237 Security Services Application Programming Interface (GSS-API) Version 238 2. GSS-API Version 2 is described in a language independent format in 239 RFC 2078 [GSSAPIv2]. The GSS-API allows a caller application to 240 authenticate a principal identity, to delegate rights to a peer, and 241 to apply security services such as confidentiality and integrity on a 242 per-message basis. 244 This document leverages the work performed by the WG in the area of 245 RFC 2078 [GSSAPIv2] the C-bindings draft [GSSAPI-C]. Whenever 246 appropriate, text has been used from the C-bindings document to 247 explain generic concepts and provide direction to the implementors. 249 The design goals of this API have been to satisfy all the 250 functionality defined in RFC 2078 and to provide these services in an 251 object oriented method. The specification also aims to satisfy the 252 needs of both types of Java application developers, those who would 253 like access to a "system-wide" GSS-API implementation, as well as 254 those who would want to provide their own "custom" implementation. 256 A "system-wide" implementation is one that is available to all 257 applications in the form of a library package. It may be a standard 258 package in the Java runtime environment (JRE) being used or it may be 259 additionally installed and accessible to any application via the 260 CLASSPATH. 262 A "custom" implementation of the GSS-API, on the other hand, is one 263 that would, in most cases, be bundled with the application during 264 distribution. It is expected that such an implementation would be 265 meant to provide for some particular need of the application, such as 266 support for some specific mechanism. 268 The design of this API also aims to provide a flexible framework to 269 add and manage GSS-API mechanisms. GSS-API leverages the JCA provider 270 concept to support the plugability of mechanisms. Mechanisms can be 271 added on a "system-wide" basis, where all users of the framework will 272 have them available. The specification also allows for the addition 273 of mechanisms per-instance the GSS-API. 275 Lastly, this specification presents an API that will naturally fit 276 within the operation environment of the Java platform. Readers are 277 assumed to be familiar with both the GSS-API and the Java platform. 279 GSS-API Java Bindings October 1999 281 2. GSS-API Operational Paradigm 283 The Generic Security Service Application Programming Interface 284 [GSSAPIv2] defines a generic security API to calling applications. 285 It allows a communicating application to authenticate the user 286 associated with another application, to delegate rights to another 287 application, and to apply security services such as confidentiality 288 and integrity on a per-message basis. 290 There are four stages to using GSS-API: 292 1) The application acquires a set of credentials with which it 293 may prove its identity to other processes. The 294 application's credentials vouch for its global identity, 295 which may or may not be related to any local username under 296 which it may be running. 298 2) A pair of communicating applications establish a joint 299 security context using their credentials. The security 300 context encapsulates shared state information, which is 301 required in order that per-message security services may be 302 provided. Examples of state information that might be 303 shared between applications as part of a security context 304 are cryptographic keys, and message sequence numbers. As 305 part of the establishment of a security context, the 306 context initiator is authenticated to the responder, and 307 may require that the responder is authenticated back to the 308 initiator. The initiator may optionally give the responder 309 the right to initiate further security contexts, acting as 310 an agent or delegate of the initiator. This transfer of 311 rights is termed "delegation", and is achieved by creating 312 a set of credentials, similar to those used by the 313 initiating application, but which may be used by the 314 responder. 316 A GSSContext object is used to establish and maintain the 317 shared information that makes up the security context. 318 Certain GSSContext methods will generate a token, which 319 applications treat as cryptographically protected, opaque 320 data. The caller of such GSSContext method is responsible 321 for transferring the token to the peer application, 322 encapsulated if necessary in an application-to-application 323 protocol. On receipt of such a token, the peer application 324 should pass it to a corresponding GSSContext method which 325 will decode the token and extract the information, updating 326 the security context state information accordingly. 328 GSS-API Java Bindings October 1999 330 3) Per-message services are invoked on a GSSContext object to 331 apply either: 333 integrity and data origin authentication, or 335 confidentiality, integrity and data origin 336 authentication 338 to application data, which are treated by GSS-API as 339 arbitrary octet-strings. An application transmitting a 340 message that it wishes to protect will call the appropriate 341 GSSContext method (getMIC or wrap) to apply protection, and 342 send the resulting token to the receiving application. The 343 receiver will pass the received token (and, in the case of 344 data protected by getMIC, the accompanying message-data) to 345 the corresponding decoding method of the GSSContext 346 interface (verifyMIC or unwrap) to remove the protection 347 and validate the data. 349 4) At the completion of a communications session (which may 350 extend across several transport connections), each 351 application uses a GSSContext method to invalidate the 352 security context and release any system or cryptographic 353 resources held. Multiple contexts may also be used (either 354 successively or simultaneously) within a single 355 communications association, at the discretion of the 356 applications. 358 3. Additional Controls 360 This section discusses the optional services that a context initiator 361 may request of the GSS-API before the context establishment. Each of 362 these services is requested by calling the appropriate mutator method 363 in the GSSContext object before the first call to init is performed. 364 Only the context initiator can request context flags. 366 The optional services defined are: 368 Delegation 369 The (usually temporary) transfer of rights from initiator to 370 acceptor, enabling the acceptor to authenticate itself as an 371 agent of the initiator. 373 Mutual Authentication 374 In addition to the initiator authenticating its identity to the 376 GSS-API Java Bindings October 1999 378 context acceptor, the context acceptor should also authenticate 379 itself to the initiator. 381 Replay Detection 382 In addition to providing message integrity services, GSSContext 383 per-message operations of getMIC and wrap should include message 384 numbering information to enable verifyMIC and unwrap to detect 385 if a message has been duplicated. 387 Out-of-Sequence Detection 388 In addition to providing message integrity services, GSSContext 389 per-message operations (getMIC and wrap) should include message 390 sequencing information to enable verifyMIC and unwrap to detect 391 if a message has been received out of sequence. 393 Anonymous Authentication 394 The establishment of the security context should not reveal the 395 initiator's identity to the context acceptor. 397 Some mechanisms may not support all optional services, and some 398 mechanisms may only support some services in conjunction with others. 399 The GSSContext interface offers query methods to allow the 400 verification by the calling application of which services will be 401 available from the context when the establishment phase is complete. 402 In general, if the security mechanism is capable of providing a 403 requested service, it should do so even if additional services must 404 be enabled in order to provide the requested service. If the 405 mechanism is incapable of providing a requested service, it should 406 proceed without the service leaving the application to abort the 407 context establishment process if it considers the requested service 408 to be mandatory. 410 Some mechanisms may specify that support for some services is 411 optional, and that implementors of the mechanism need not provide it. 412 This is most commonly true of the confidentiality service, often 413 because of legal restrictions on the use of data-encryption, but may 414 apply to any of the services. Such mechanisms are required to send 415 at least one token from acceptor to initiator during context 416 establishment when the initiator indicates a desire to use such a 417 service, so that the initiating GSS-API can correctly indicate 418 whether the service is supported by the acceptor's GSS-API. 420 3.1. Delegation 422 The GSS-API allows delegation to be controlled by the initiating 423 application via the requestCredDeleg method before the first call to 424 init has been issued. Some mechanisms do not support delegation, and 426 GSS-API Java Bindings October 1999 428 for such mechanisms attempts by an application to enable delegation 429 are ignored. 431 The acceptor of a security context, for which the initiator enabled 432 delegation, can check if delegation was enabled by using the 433 getCredDelegState method of the GSSContext interface. In cases when 434 it is, the delegated credential object can be obtained by calling the 435 getDelegCred method. The obtained GSSCredential object may then be 436 used to initiate subsequent GSS-API security contexts as an agent or 437 delegate of the initiator. If the original initiator's identity is 438 "A" and the delegate's identity is "B", then, depending on the 439 underlying mechanism, the identity embodied by the delegated 440 credential may be either "A" or "B acting for A". 442 For many mechanisms that support delegation, a simple boolean does 443 not provide enough control. Examples of additional aspects of 444 delegation control that a mechanism might provide to an application 445 are duration of delegation, network addresses from which delegation 446 is valid, and constraints on the tasks that may be performed by a 447 delegate. Such controls are presently outside the scope of the GSS- 448 API. GSS-API implementations supporting mechanisms offering 449 additional controls should provide extension routines that allow 450 these controls to be exercised (perhaps by modifying the initiator's 451 GSS-API credential object prior to its use in establishing a 452 context). However, the simple delegation control provided by GSS-API 453 should always be able to over-ride other mechanism-specific 454 delegation controls. If the application instructs the GSSContext 455 object that delegation is not desired, then the implementation must 456 not permit delegation to occur. This is an exception to the general 457 rule that a mechanism may enable services even if they are not 458 requested - delegation may only be provided at the explicit request 459 of the application. 461 3.2. Mutual Authentication 463 Usually, a context acceptor will require that a context initiator 464 authenticate itself so that the acceptor may make an access-control 465 decision prior to performing a service for the initiator. In some 466 cases, the initiator may also request that the acceptor authenticate 467 itself. GSS-API allows the initiating application to request this 468 mutual authentication service by calling the requestMutualAuth method 469 of the GSSContext interface with a "true" parameter before making the 470 first call to init. The initiating application is informed as to 471 whether or not the context acceptor has authenticated itself. Note 472 that some mechanisms may not support mutual authentication, and other 473 mechanisms may always perform mutual authentication, whether or not 474 the initiating application requests it. In particular, mutual 476 GSS-API Java Bindings October 1999 478 authentication may be required by some mechanisms in order to support 479 replay or out-of-sequence message detection, and for such mechanisms 480 a request for either of these services will automatically enable 481 mutual authentication. 483 3.3. Replay and Out-of-Sequence Detection 485 The GSS-API may provide detection of mis-ordered messages once a 486 security context has been established. Protection may be applied to 487 messages by either application, by calling either getMIC or wrap 488 methods of the GSSContext interface, and verified by the peer 489 application by calling verifyMIC or unwrap for the peer's GSSContext 490 object. 492 The getMIC method calculates a cryptographic checksum of an 493 application message, and returns that checksum in a token. The 494 application should pass both the token and the message to the peer 495 application, which presents them to the verifyMIC method of the 496 peer's GSSContext object. 498 The wrap method calculates a cryptographic checksum of an application 499 message, and places both the checksum and the message inside a single 500 token. The application should pass the token to the peer 501 application, which presents it to the unwrap method of the peer's 502 GSSContext object to extract the message and verify the checksum. 504 Either pair of routines may be capable of detecting out-of-sequence 505 message delivery, or duplication of messages. Details of such mis- 506 ordered messages are indicated through supplementary query methods of 507 the MessageProp object that is filled in by each of these routines. 509 A mechanism need not maintain a list of all tokens that have been 510 processed in order to support these status codes. A typical 511 mechanism might retain information about only the most recent "N" 512 tokens processed, allowing it to distinguish duplicates and missing 513 tokens within the most recent "N" messages; the receipt of a token 514 older than the most recent "N" would result in the isOldToken method 515 of the instance of MessageProp to return "true". 517 3.4. Anonymous Authentication 519 In certain situations, an application may wish to initiate the 520 authentication process to authenticate a peer, without revealing its 521 own identity. As an example, consider an application providing 522 access to a database containing medical information, and offering 523 unrestricted access to the service. A client of such a service might 525 GSS-API Java Bindings October 1999 527 wish to authenticate the service (in order to establish trust in any 528 information retrieved from it), but might not wish the service to be 529 able to obtain the client's identity (perhaps due to privacy concerns 530 about the specific inquiries, or perhaps simply to avoid being placed 531 on mailing-lists). 533 In normal use of the GSS-API, the initiator's identity is made 534 available to the acceptor as a result of the context establishment 535 process. However, context initiators may request that their identity 536 not be revealed to the context acceptor. Many mechanisms do not 537 support anonymous authentication, and for such mechanisms the request 538 will not be honored. An authentication token will still be 539 generated, but the application is always informed if a requested 540 service is unavailable, and has the option to abort context 541 establishment if anonymity is valued above the other security 542 services that would require a context to be established. 544 In addition to informing the application that a context is 545 established anonymously (via the isAnonymous method of the GSSContext 546 class), the getSrcName method of the acceptor's GSSContext object 547 will, for such contexts, return a reserved internal-form name, 548 defined by the implementation. 550 The toString method for a GSSName object representing an anonymous 551 entity will return a printable name. The returned value will be 552 syntactically distinguishable from any valid principal name supported 553 by the implementation. The associated name-type object identifier 554 will be an oid representing the value of NT_ANONYMOUS. This name- 555 type oid will be defined as a public, static Oid object of the 556 GSSName class. The printable form of an anonymous name should be 557 chosen such that it implies anonymity, since this name may appear in, 558 for example, audit logs. For example, the string "" might 559 be a good choice, if no valid printable names supported by the 560 implementation can begin with "<" and end with ">". 562 When using the equal method of the GSSName interface, and one of the 563 operands is a GSSName instance representing an anonymous entity, the 564 method must return "false". 566 3.5. Confidentiality 568 If a GSSContext supports the confidentiality service, wrap method may 569 be used to encrypt application messages. Messages are selectively 570 encrypted, under the control of the setPrivacy method of the 571 MessageProp object used in the wrap method. 573 GSS-API Java Bindings October 1999 575 3.6. Inter-process Context Transfer 577 GSS-API V2 provides functionality which allows a security context to 578 be transferred between processes on a single machine. These are 579 implemented using the export method of GSSContext and a byte array 580 constructor of the same class. The most common use for such a 581 feature is a client-server design where the server is implemented as 582 a single process that accepts incoming security contexts, which then 583 launches child processes to deal with the data on these contexts. In 584 such a design, the child processes must have access to the security 585 context object created within the parent so that they can use per- 586 message protection services and delete the security context when the 587 communication session ends. 589 Since the security context data structure is expected to contain 590 sequencing information, it is impractical in general to share a 591 context between processes. Thus GSSContext interface provides an 592 export method that the process, which currently owns the context, can 593 call to declare that it has no intention to use the context 594 subsequently, and to create an inter-process token containing 595 information needed by the adopting process to successfully re-create 596 the context. After successful completion of export, the original 597 security context is made inaccessible to the calling process by GSS- 598 API and any further usage of this object will result in failures. 599 The originating process transfers the inter-process token to the 600 adopting process, which creates a new GSSContext object using the 601 byte array constructor. The properties of the context are equivalent 602 to that of the original context. 604 The inter-process token may contain sensitive data from the original 605 security context (including cryptographic keys). Applications using 606 inter-process tokens to transfer security contexts must take 607 appropriate steps to protect these tokens in transit. 609 Implementations are not required to support the inter-process 610 transfer of security contexts. Calling the isTransferable method of 611 the GSSContext interface will indicate if the context object is 612 transferable. 614 3.7. The Use of Incomplete Contexts 616 Some mechanisms may allow the per-message services to be used before 617 the context establishment process is complete. For example, a 618 mechanism may include sufficient information in its initial context- 619 level tokens for the context acceptor to immediately decode messages 620 protected with wrap or getMIC. For such a mechanism, the initiating 621 application need not wait until subsequent context-level tokens have 623 GSS-API Java Bindings October 1999 625 been sent and received before invoking the per-message protection 626 services. 628 An application can invoke the isProtReady method of the GSSContext 629 class to determine if the per-message services are available in 630 advance of complete context establishment. Applications wishing to 631 use per-message protection services on partially-established contexts 632 should query this method before attempting to invoke wrap or getMIC. 634 4. Calling Conventions 636 Java provides the implementors with not just a syntax for the 637 language, but also an operational environment. For example, memory 638 is automatically managed and does not require application 639 intervention. These language features have allowed for a simpler API 640 and have led to the elimination of certain GSS-API functions. 642 Moreover, the Java Cryptographic Architecture (JCA) defines a 643 provider model which allows an implementation independent access to 644 its security services. Using this model, applications can seamlessly 645 switch between different implementations and dynamically add new 646 services. The GSS-API specification leverages these concepts by the 647 usage of providers for the mechanism implementations. 649 4.1. Package Name 651 The classes and interfaces defined in this document reside in the 652 package called "org.ietf.jgss". Applications that wish to make use 653 of this API should import this package name as shows in section 7. 655 4.2. Provider Framework 657 The Java security API's use a provider architecture that allows 658 applications to be implementation independent and security API 659 implementations to be modular and extensible. The 660 java.security.Provider class is an abstract class that a vendor 661 extends. This class maps various properties that represent different 662 security services that are available to the names of the actual 663 vendor classes that implement those services. When requesting a 664 service, an application simply specifies the desired provider and the 665 API delegates the request to service classes available from that 666 provider. 668 GSS-API Java Bindings October 1999 670 Using the Java security provider model insulates applications from 671 implementation details of the services they wish to use. 672 Applications can switch between providers easily and new providers 673 can be added as needed, even at runtime. 675 The GSS-API may use providers to find components for specific 676 underlying security mechanisms. For instance, a particular provider 677 might contain components that will allow the GSS-API to support the 678 Kerberos v5 mechanism and another might contain components to support 679 the SPKM mechanism. By delegating mechanism specific functionality 680 to the components obtained from providers the GSS-API can be extended 681 to support an arbitrary list of mechanism. 683 How the GSS-API locates and queries these providers is beyond the 684 scope of this document and is being deferred to a Service Provider 685 Interface (SPI) specification. The availability of such a SPI 686 specification is not mandatory for the adoption of this API 687 specification nor is it mandatory to use providers in the 688 implementation of a GSS-API framework. However, by using the provider 689 framework together with an SPI specification one can create an 690 extensible and implementation independent GSS-API framework. 692 4.3. Integer types 694 All numeric values are declared as "int" primitive Java type. The 695 Java specification guarantees that this will be a 32 bit two's 696 complement signed number. 698 Throughout this API, the "boolean" primitive Java type is used 699 wherever a boolean value is required or returned. 701 4.4. Opaque Data types 703 Java byte arrays are used to represent opaque data types which are 704 consumed and produced by the GSS-API in the forms of tokens. Java 705 arrays contain a length field which enables the users to easily 706 determine their size. The language has automatic garbage collection 707 which alleviates the need by developers to release memory and 708 simplifies buffer ownership issues. 710 4.5. Strings 712 The String object will be used to represent all textual data. The 713 Java String object, transparently treats all characters as two-byte 714 Unicode characters which allows support for many locals. All 716 GSS-API Java Bindings October 1999 718 routines returning or accepting textual data will use the String 719 object. 721 4.6. Object Identifiers 723 An Oid object will be used to represent Universal Object Identifiers 724 (Oids). Oids are ISO-defined, hierarchically globally-interpretable 725 identifiers used within the GSS-API framework to identify security 726 mechanisms and name formats. The Oid object can be created from a 727 string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as 728 well as from its ASN.1 DER encoding. Methods are also provided to 729 test equality and provide the DER representation for the object. 731 An important feature of the Oid class is that its instances are 732 immutable - i.e. there are no methods defined that allow one to 733 change the contents of an Oid. This property allows one to treat 734 these objects as "statics" without the need to perform copies. 736 Certain routines allow the usage of a default oid. A "null" value 737 can be used in those cases. 739 4.7. Object Identifier Sets 741 The Java bindings represents object identifiers sets as arrays of Oid 742 objects. All Java arrays contain a length field which allows for 743 easy manipulation and reference. 745 In order to support the full functionality of RFC 2078, the Oid class 746 includes a method which checks for existence of an Oid object within 747 a specified array. This is equivalent in functionality to 748 gss_test_oid_set_member. The use of Java arrays and Java's automatic 749 garbage collection has eliminated the need for the following 750 routines: gss_create_empty_oid_set, gss_release_oid_set, and 751 gss_add_oid_set_member. Java GSS-API implementations will not 752 contain them. Java's automatic garbage collection and the immutable 753 property of the Oid object eliminates the complicated memory 754 management issues of the C counterpart. 756 When ever a default value for an Object Identifier Set is required, a 757 "null" value can be used. Please consult the detailed method 758 description for details. 760 4.8. Credentials 762 GSS-API credentials are represented by the GSSCredential interface. 764 GSS-API Java Bindings October 1999 766 The interface contains several constructs to allow for the creation 767 of most common credential objects for the initiator and the acceptor. 768 Comparisons are performed using the interface's "equals" method. The 769 following general description of GSS-API credentials is included from 770 the C-bindings specification: 772 GSS-API credentials can contain mechanism-specific principal 773 authentication data for multiple mechanisms. A GSS-API credential is 774 composed of a set of credential-elements, each of which is applicable 775 to a single mechanism. A credential may contain at most one 776 credential-element for each supported mechanism. A credential- 777 element identifies the data needed by a single mechanism to 778 authenticate a single principal, and conceptually contains two 779 credential-references that describe the actual mechanism-specific 780 authentication data, one to be used by GSS-API for initiating 781 contexts, and one to be used for accepting contexts. For mechanisms 782 that do not distinguish between acceptor and initiator credentials, 783 both references would point to the same underlying mechanism-specific 784 authentication data. 786 Credentials describe a set of mechanism-specific principals, and give 787 their holder the ability to act as any of those principals. All 788 principal identities asserted by a single GSS-API credential should 789 belong to the same entity, although enforcement of this property is 790 an implementation-specific matter. A single GSSCredential object 791 represents all the credential elements that have been acquired. 793 The creation's of an GSSContext object allows the value of "null" to 794 be specified as the GSSCredential input parameter. This will 795 indicate a desire by the application to act as a default principal. 796 While individual GSS-API implementations are free to determine such 797 default behavior as appropriate to the mechanism, the following 798 default behavior by these routines is recommended for portability: 800 For the initiator side of the context: 802 1) If there is only a single principal capable of initiating 803 security contexts for the chosen mechanism that the 804 application is authorized to act on behalf of, then that 805 principal shall be used, otherwise 807 2) If the platform maintains a concept of a default network- 808 identity for the chosen mechanism, and if the application 809 is authorized to act on behalf of that identity for the 810 purpose of initiating security contexts, then the principal 811 corresponding to that identity shall be used, otherwise 813 3) If the platform maintains a concept of a default local 815 GSS-API Java Bindings October 1999 817 identity, and provides a means to map local identities into 818 network-identities for the chosen mechanism, and if the 819 application is authorized to act on behalf of the network- 820 identity image of the default local identity for the 821 purpose of initiating security contexts using the chosen 822 mechanism, then the principal corresponding to that 823 identity shall be used, otherwise 825 4) A user-configurable default identity should be used. 827 and for the acceptor side of the context 829 1) If there is only a single authorized principal identity 830 capable of accepting security contexts for the chosen 831 mechanism, then that principal shall be used, otherwise 833 2) If the mechanism can determine the identity of the target 834 principal by examining the context-establishment token 835 processed during the accept method, and if the accepting 836 application is authorized to act as that principal for the 837 purpose of accepting security contexts using the chosen 838 mechanism, then that principal identity shall be used, 839 otherwise 841 3) If the mechanism supports context acceptance by any 842 principal, and if mutual authentication was not requested, 843 any principal that the application is authorized to accept 844 security contexts under using the chosen mechanism may be 845 used, otherwise 847 4) A user-configurable default identity shall be used. 849 The purpose of the above rules is to allow security contexts to be 850 established by both initiator and acceptor using the default behavior 851 whenever possible. Applications requesting default behavior are 852 likely to be more portable across mechanisms and implementations than 853 ones that instantiate an GSSCredential object representing a specific 854 identity. 856 4.9. Contexts 858 The GSSContext interface is used to represent one end of a GSS-API 859 security context, storing state information appropriate to that end 860 of the peer communication, including cryptographic state information. 862 GSS-API Java Bindings October 1999 864 The instantiation of the context object is done differently by the 865 initiator and the acceptor. After the context has been instantiated, 866 the initiator may choose to set various context options which will 867 determine the characteristics of the desired security context. When 868 all the application desired characteristics have been set, the 869 initiator will call the initSecContext method which will produce a 870 token for consumption by the peer's acceptSecContext method. It is 871 the responsibility of the application to deliver the authentication 872 token(s) between the peer applications for processing. Upon 873 completion of the context establishment phase, context attributes can 874 be retrieved, by both the initiator and acceptor, using the accessor 875 methods. These will reflect the actual attributes of the established 876 context. At this point the context can be used by the application to 877 apply cryptographic services to its data. 879 4.10. Authentication tokens 881 A token is a caller-opaque type that GSS-API uses to maintain 882 synchronization between each end of the GSS-API security context. 883 The token is a cryptographically protected octet-string, generated by 884 the underlying mechanism at one end of a GSS-API security context for 885 use by the peer mechanism at the other end. Encapsulation (if 886 required) within the application protocol and transfer of the token 887 are the responsibility of the peer applications. 889 Java GSS-API uses byte arrays to represent authentication tokens. 890 Overloaded methods exist which allow the caller to supply input and 891 output streams which will be used for the reading and writing of the 892 token data. 894 4.11. Interprocess tokens 896 Certain GSS-API routines are intended to transfer data between 897 processes in multi-process programs. These routines use a caller- 898 opaque octet-string, generated by the GSS-API in one process for use 899 by the GSS-API in another process. The calling application is 900 responsible for transferring such tokens between processes. Note 901 that, while GSS-API implementors are encouraged to avoid placing 902 sensitive information within interprocess tokens, or to 903 cryptographically protect them, many implementations will be unable 904 to avoid placing key material or other sensitive data within them. 905 It is the application's responsibility to ensure that interprocess 906 tokens are protected in transit, and transferred only to processes 907 that are trustworthy. An interprocess token is represented using a 908 byte array emitted from the export method of the GSSContext 909 interface. The receiver of the interprocess token would initialize 911 GSS-API Java Bindings October 1999 913 an GSSContext object with this token to create a new context. Once a 914 context has been exported, the GSSContext object is invalidated and 915 is no longer available. 917 4.12. Error Reporting 919 RFC 2078 defined the usage of major and minor status values for 920 signaling of GSS-API errors. The major code, also called GSS status 921 code, is used to signal errors at the GSS-API level independent of 922 the underlying mechanism(s). The minor status value or Mechanism 923 status code, is a mechanism defined error value indicating a 924 mechanism specific error code. 926 Java GSS-API uses exceptions implemented by the GSSException class to 927 signal both minor and major error values. Both, mechanism specific 928 errors and GSS-API level errors are signaled through instances of 929 this class. The usage of exceptions replaces the need for major and 930 minor codes to be used within the API calls. GSSException class also 931 contains methods to obtain textual representations for both the major 932 and minor values, which is equivalent to the functionality of 933 gss_display_status. 935 4.12.1. GSS status codes 937 GSS status codes indicate errors that are independent of the 938 underlying mechanism(s) used to provide the security service. The 939 errors that can be indicated via a GSS status code are generic API 940 routine errors (errors that are defined in the GSS-API 941 specification). These bindings take advantage of the Java exceptions 942 mechanism, thus eliminating the need for calling errors. 944 A GSS status code indicates a single fatal generic API error from the 945 routine that has thrown the GSSException. Using exceptions announces 946 that a fatal error has occurred during the execution of the method. 947 The GSS-API operational model also allows for the signaling of 948 supplementary status information from the per-message calls. These 949 need to be handled as return values since using exceptions is not 950 appropriate for informatory or warning-like information. The methods 951 that are capable of producing supplementary information are the two 952 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 953 These methods fill the supplementary status codes in the MessageProp 954 object that was passed in. 956 GSSException object, along with providing the functionality for 957 setting of the various error codes and translating them into textual 958 representation, also contains the definitions of all the numeric 960 GSS-API Java Bindings October 1999 962 error values. The following table lists the definitions of error 963 codes: 965 Table: GSS Status Codes 967 Name Value Meaning 969 BAD_MECH 1 An unsupported mechanism 970 was requested. 972 BAD_NAME 2 An invalid name was supplied. 974 BAD_NAMETYPE 3 A supplied name was of an 975 unsupported type. 977 BAD_BINDINGS 4 Incorrect channel bindings were 978 supplied. 980 BAD_STATUS 5 An invalid status code was 981 supplied. 983 BAD_MIC 6 A token had an invalid MIC. 985 NO_CRED 7 No credentials were supplied, or 986 the credentials were unavailable 987 or inaccessible. 989 NO_CONTEXT 8 Invalid context has been 990 supplied. 992 DEFECTIVE_TOKEN 9 A supplied token was invalid. 994 DEFECTIVE_CREDENTIAL 10 A supplied credential was 995 invalid. 997 CREDENTIALS_EXPIRED 11 The referenced credentials 998 have expired. 1000 CONTEXT_EXPIRED 12 The context has expired. 1002 FAILURE 13 Miscellaneous failure, 1003 unspecified at the GSS-API level. 1005 BAD_QOP 14 The quality-of-protection 1006 requested could not be provided. 1008 UNAUTHORIZED 15 The operation is forbidden by 1010 GSS-API Java Bindings October 1999 1012 local security policy. 1014 UNAVAILABLE 16 The operation or option is 1015 unavailable. 1017 DUPLICATE_ELEMENT 17 The requested credential 1018 element already exists. 1020 NAME_NOT_MN 18 The provided name was not a 1021 mechanism name. 1023 OLD_TOKEN 19 The token's validity period has 1024 expired. 1026 DUPLICATE_TOKEN 20 The token was a duplicate of an 1027 earlier version. 1029 The GSS major status code of FAILURE is used to indicate that the 1030 underlying mechanism detected an error for which no specific GSS 1031 status code is defined. The mechanism-specific status code can 1032 provide more details about the error. 1034 4.12.2. Mechanism-specific status codes 1036 Mechanism-specific status codes are communicated in two ways, they 1037 are part of any GSSException thrown from the mechanism specific layer 1038 to signal a fatal error, or they are part of the MessageProp object 1039 that the per-message calls use to signal non-fatal errors. 1041 A default value of 0 in either the GSSException object or the 1042 MessageProp object will be used to represent the absence of any 1043 mechanism specific status code. 1045 4.12.3. Supplementary status codes 1047 Supplementary status codes are confined to the per-message methods of 1048 the GSSContext interface. Because of the informative nature of these 1049 errors it is not appropriate to use exceptions to signal them. 1050 Instead, the per-message operations of the GSSContext interface 1051 return these values in a MessageProp object. 1053 The MessageProp class defines query methods which return boolean 1054 values indicating the following supplementary states: 1056 GSS-API Java Bindings October 1999 1058 Table: Supplementary Status Methods 1060 Method Name Meaning when "true" is returned 1062 isDuplicateToken The token was a duplicate of an 1063 earlier token. 1065 isOldToken The token's validity period has 1066 expired. 1068 isUnseqToken A later token has already been 1069 processed. 1071 isGapToken An expected per-message token was 1072 not received. 1074 "true" return value for any of the above methods indicates that the 1075 token exhibited the specified property. The application must 1076 determine the appropriate course of action for these supplementary 1077 values. They are not treated as errors by the GSS-API. 1079 4.13. Names 1081 A name is used to identify a person or entity. GSS-API authenticates 1082 the relationship between a name and the entity claiming the name. 1084 Since different authentication mechanisms may employ different 1085 namespaces for identifying their principals, GSS-API's naming support 1086 is necessarily complex in multi-mechanism environments (or even in 1087 some single-mechanism environments where the underlying mechanism 1088 supports multiple namespaces). 1090 Two distinct conceptual representations are defined for names: 1092 1) A GSS-API form represented by implementations of the GSSName 1093 interface: A single GSSName object may contain multiple names 1094 from different namespaces, but all names should refer to the 1095 same entity. An example of such an internal name would be the 1096 name returned from a call to the getName method of the 1097 GSSCredential interface, when applied to a credential containing 1098 credential elements for multiple authentication mechanisms 1099 employing different namespaces. This GSSName object will 1100 contain a distinct name for the entity for each authentication 1101 mechanism. 1103 GSS-API Java Bindings October 1999 1105 For GSS-API implementations supporting multiple namespaces, 1106 GSSName implementations must contain sufficient information to 1107 determine the namespace to which each primitive name belongs. 1109 2) Mechanism-specific contiguous byte array and string forms: 1110 Different GSSName initialization methods are provided to handle 1111 both byte array and string formats and to accommodate various 1112 calling applications and name types. These formats are capable 1113 of containing only a single name (from a single namespace). 1114 Contiguous string names are always accompanied by an object 1115 identifier specifying the namespace to which the name belongs, 1116 and their format is dependent on the authentication mechanism 1117 that employs that name. The string name forms are assumed to be 1118 printable, and may therefore be used by GSS-API applications for 1119 communication with their users. The byte array name formats are 1120 assumed to be in non-printable formats (e.g. the byte array 1121 returned from the export method of the GSSName interface). 1123 An GSSName object can be converted to a contiguous representation by 1124 using the toString method. This will guarantee that the name will be 1125 converted to a printable format. Different initialization methods in 1126 the GSSName interface are defined allowing support for multiple 1127 syntaxes for each supported namespace, and allowing users the freedom 1128 to choose a preferred name representation. The toString method 1129 should use an implementation-chosen printable syntax for each 1130 supported name-type. To obtain the printable name type, 1131 getStringNameType method can be used. 1133 There is no guarantee that calling the toString method on the GSSName 1134 interface will produce the same string form as the original imported 1135 string name. Furthermore, it is possible that the name was not even 1136 constructed from a string representation. The same applies to name- 1137 space identifiers which may not necessarily survive unchanged after a 1138 journey through the internal name-form. An example of this might be 1139 a mechanism that authenticates X.500 names, but provides an 1140 algorithmic mapping of Internet DNS names into X.500. That 1141 mechanism's implementation of GSSName might, when presented with a 1142 DNS name, generate an internal name that contained both the original 1143 DNS name and the equivalent X.500 name. Alternatively, it might only 1144 store the X.500 name. In the latter case, the toString method of 1145 GSSName would most likely generate a printable X.500 name, rather 1146 than the original DNS name. 1148 The context acceptor can obtain an GSSName object representing the 1149 entity performing the context initiation (through the usage of 1150 getSrcName method). Since this name has been authenticated by a 1151 single mechanism, it contains only a single name (even if the 1152 internal name presented by the context initiator to the GSSContext 1154 GSS-API Java Bindings October 1999 1156 object had multiple components). Such names are termed internal 1157 mechanism names, or "MN"s and the names emitted by GSSContext 1158 interface in the getSrcName and getTargName are always of this type. 1159 Since some applications may require MNs without wanting to incur the 1160 overhead of an authentication operation, creation methods are 1161 provided that take not only the name buffer and name type, but also 1162 the mechanism oid for which this name should be created. When 1163 dealing with an existing GSSName object, the canonicalize method may 1164 be invoked to convert a general internal name into an MN. 1166 GSSName objects can be compared using their equal method, which 1167 returns "true" if the two names being compared refer to the same 1168 entity. This is the preferred way to perform name comparisons 1169 instead of using the printable names that a given GSS-API 1170 implementation may support. Since GSS-API assumes that all primitive 1171 names contained within a given internal name refer to the same 1172 entity, equal can return "true" if the two names have at least one 1173 primitive name in common. If the implementation embodies knowledge 1174 of equivalence relationships between names taken from different 1175 namespaces, this knowledge may also allow successful comparisons of 1176 internal names containing no overlapping primitive elements. 1178 When used in large access control lists, the overhead of creating an 1179 GSSName object on each name and invoking the equal method on each 1180 name from the ACL may be prohibitive. As an alternative way of 1181 supporting this case, GSS-API defines a special form of the 1182 contiguous byte array name which may be compared directly (byte by 1183 byte). Contiguous names suitable for comparison are generated by the 1184 export method. Exported names may be re-imported by using the byte 1185 array constructor and specifying the NT_EXPORT_NAME as the name type 1186 object identifier. The resulting GSSName name will also be a MN. 1187 The GSSName interface defines public static Oid objects representing 1188 the standard name types. Structurally, an exported name object 1189 consists of a header containing an OID identifying the mechanism that 1190 authenticated the name, and a trailer containing the name itself, 1191 where the syntax of the trailer is defined by the individual 1192 mechanism specification. Detailed description of the format is 1193 specified in the language-independent GSS-API specification 1194 [GSSAPIv2]. 1196 Note that the results obtained by using the equals method will in 1197 general be different from those obtained by invoking canonicalize and 1198 export, and then comparing the byte array output. The first series 1199 of operation determines whether two (unauthenticated) names identify 1200 the same principal; the second whether a particular mechanism would 1201 authenticate them as the same principal. These two operations will 1202 in general give the same results only for MNs. 1204 GSS-API Java Bindings October 1999 1206 It is important to note that the above are guidelines as how GSSName 1207 implementations should behave, and are not intended to be specific 1208 requirements of how names objects must be implemented. The mechanism 1209 designers are free to decide on the details of their implementations 1210 of the GSSName interface as long as the behavior satisfies the above 1211 guidelines. 1213 4.14. Channel Bindings 1215 GSS-API supports the use of user-specified tags to identify a given 1216 context to the peer application. These tags are intended to be used 1217 to identify the particular communications channel that carries the 1218 context. Channel bindings are communicated to the GSS-API using the 1219 ChannelBinding object. The application may use byte arrays to 1220 specify the application data to be used in the channel binding as 1221 well as using instances of the InetAddress. The InetAddress for the 1222 initiator and/or acceptor can be used within an instance of a 1223 ChannelBinding. ChannelBinding can be set for the GSSContext object 1224 using the setChannelBinding method before the first call to init or 1225 accept has been performed. Unless the setChannelBinding method has 1226 been used to set the ChannelBinding for an GSSContext object, "null" 1227 ChannelBinding will be assumed. InetAddress is currently the only 1228 address type defined within the Java platform and as such, it is the 1229 only one supported within the ChannelBinding class. Applications 1230 that use other types of addresses can include them as part of the 1231 application specific data. 1233 Conceptually, the GSS-API concatenates the initiator and acceptor 1234 address information, and the application supplied byte array to form 1235 an octet string. The mechanism calculates a MIC over this octet 1236 string and binds the MIC to the context establishment token emitted 1237 by init method of the GSSContext interface. The same bindings are 1238 set by the context acceptor for its GSSContext object and during 1239 processing of the accept method a MIC is calculated in the same way. 1240 The calculated MIC is compared with that found in the token, and if 1241 the MICs differ, accept will throw a GSSException with the major 1242 code set to BAD_BINDINGS, and the context will not be established. 1243 Some mechanisms may include the actual channel binding data in the 1244 token (rather than just a MIC); applications should therefore not use 1245 confidential data as channel-binding components. 1247 Individual mechanisms may impose additional constraints on addresses 1248 that may appear in channel bindings. For example, a mechanism may 1249 verify that the initiator address field of the channel binding 1250 contains the correct network address of the host system. Portable 1251 applications should therefore ensure that they either provide correct 1252 information for the address fields, or omit setting of the addressing 1254 GSS-API Java Bindings October 1999 1256 information. 1258 4.15. Stream Objects 1260 The context object provides overloaded methods which use input and 1261 output streams as the means to convey authentication and per-message 1262 GSS-API tokens. It is important to note that the streams are 1263 expected to contain the usual GSS-API tokens which would otherwise be 1264 handled through the usage of byte arrays. The tokens are expected to 1265 have a definite start and an end. The callers are responsible for 1266 ensuring that the supplied streams will not block, or expect to block 1267 until a full token is processed by the GSS-API method. Only a single 1268 GSS-API token will be processed per invocation of the stream based 1269 method. 1271 The usage of streams allows the callers to have control and 1272 management of the supplied buffers. Because streams are non- 1273 primitive objects, the callers can make the streams as complicated or 1274 as simple as desired simply by using the streams defined in the 1275 java.io package or creating their own through the use of inheritance. 1276 This will allow for the application's greatest flexibility. 1278 4.16. Optional Parameters 1280 Whenever the application wishes to omit an optional parameter the 1281 "null" value shall be used. The detailed method descriptions 1282 indicate which parameters are optional. Methods overloading has also 1283 been used as a technique to indicate default parameters. 1285 5. Introduction to GSS-API Classes and Interfaces 1287 This section presents a brief description of the classes and 1288 interfaces that constitute the GSS-API. The implementations of these 1289 are obtained from the CLASSPATH defined by the application. If Java 1290 GSS becomes part of the standard Java API's then these classes will 1291 be available by default on all systems as part of the JRE's system 1292 classes. 1294 This section also shows the corresponding RFC 2078 functionality 1295 implemented by each of the classes. Detailed description of these 1296 classes and their methods is presented in section 6. 1298 GSS-API Java Bindings October 1999 1300 5.1. GSSManager class 1302 This class serves as a factory to instantiate implementations of the 1303 GSS-API interfaces and also provides methods to make queries about 1304 underlying security mechanisms. How this class locates and 1305 communicates with components from the underlying security mechanisms 1306 is outside the scope of this document, but may be specified in 1307 whatever SPI the GSSManager implementation follows. 1309 Applications that desire to provide their own implementation of the 1310 GSSManager class can simply extend the standard GSSManager class and 1311 instantiate the new subclass. However, it is recommended that rather 1312 than replacing the implementation, they enable the existing 1313 implementation to support their needs by providing the necessary 1314 components via the SPI that it follows. 1316 This class contains equivalents of the following RFC 2078 routines: 1318 RFC 2078 Routine Function Section 1320 gss_import_name Create an internal name from 6.1.9- 1321 the supplied information. 6.1.12 1323 gss_acquire_cred Acquire credential 6.1.13- 1324 for use. 6.1.15 1326 gss_import_sec_context Create a previously exported 6.1.18 1327 context. 1329 gss_indicate_mechs List the mechanisms 6.1.6 1330 supported by this GSS-API 1331 implementation. 1333 gss_inquire_mechs_for_name List the mechanisms 6.1.8 1334 supporting the 1335 specified name type. 1337 gss_inquire_names_for_mech List the name types 6.1.7 1338 supported by the 1339 specified mechanism. 1341 5.2. GSSName interface 1343 GSS-API names are represented in the Java bindings through the 1345 GSS-API Java Bindings October 1999 1347 GSSName interface. Different name formats and their definitions are 1348 identified with universal Object Identifiers (oids). The format of 1349 the names can be derived based on the unique oid of each name type. 1350 The following GSS-API routines are provided by the GSSName interface: 1352 RFC 2078 Routine Function Section(s) 1354 gss_display_name Covert internal name 6.2.7 1355 representation to text format. 1357 gss_compare_name Compare two internal names. 6.2.3, 6.2.4 1359 gss_release_name Release resources associated N/A 1360 with the internal name. 1362 gss_canonicalize_name Convert an internal name to a 6.1.11, 1363 mechanism name. 1365 gss_export_name Convert a mechanism name to 6.2.6 1366 export format. 1368 gss_duplicate_name Create a copy of the internal N/A 1369 name. 1371 The gss_release_name call is not provided as Java does its own 1372 garbage collection. The gss_duplicate_name call is also redundant; 1373 the GSSName interface has no mutator methods that can change the 1374 state of the object so it is safe for sharing. 1376 5.3. GSSCredential interface 1378 The GSSCredential interface is responsible for the encapsulation of 1379 GSS-API credentials. Credentials identify a single entity and 1380 provide the necessary cryptographic information to enable the 1381 creation of a context on behalf of that entity. A single credential 1382 may contain multiple mechanism specific credentials, each referred to 1383 as a credential element. The GSSCredential interface provides the 1384 functionality of the following GSS-API routines: 1386 RFC 2078 Routine Function Section(s) 1388 gss_add_cred Constructs credentials 6.3.12 1389 incrementally. 1391 GSS-API Java Bindings October 1999 1393 gss_inquire_cred Obtain information about 6.3.4,6.3.5 1394 credential. 1396 gss_inquire_cred_by_mech Obtain per-mechanism 6.3.5-6.3.10 1397 information about 1398 a credential. 1400 gss_release_cred Disposes of credentials 6.3.3 1401 after use. 1403 5.4. GSSContext interface 1405 This interface encapsulates the functionality of context-level calls 1406 required for security context establishment and management between 1407 peers as well as the per-message services offered to applications. A 1408 context is established between a pair of peers and allows the usage 1409 of security services on a per-message basis on application data. It 1410 is created over a single security mechanism. The GSSContext 1411 interface provides the functionality of the following GSS-API 1412 routines: 1414 RFC 2078 Routine Function Section(s) 1416 gss_init_sec_context Initiate the creation of a 6.4.3, 1417 security context with a peer. 6.4.4 1419 gss_accept_sec_context Accept a security context 6.4.5, 1420 initiated by a peer. 6.4.6 1422 gss_delete_sec_context Destroy a security context. 6.4.8 1424 gss_context_time Obtain remaining context 6.4.37 1425 time. 1427 gss_inquire_context Obtain context 6.4.29 to 1428 characteristics. 6.3.42 1430 gss_wrap_size_limit Determine token-size limit 6.4.9 1431 for gss_wrap. 1433 gss_export_sec_context Transfer security context 6.4.18 1434 to another process. 1436 GSS-API Java Bindings October 1999 1438 gss_get_mic Calculate a cryptographic 6.4.14, 1439 Message Integrity Code (MIC) 6.4.15 1440 for a message. 1442 gss_verify_mic Verify integrity on a received 6.4.16, 1443 message. 6.4.17 1445 gss_wrap Attach a MIC to a message and 6.4.10, 1446 optionally encrypt the message 6.4.11 1447 content. 1449 gss_unwrap Obtain a previously wrapped 6.4.12, 1450 application message verifying 6.4.13 1451 its integrity and optionally 1452 decrypting it. 1454 The functionality offered by the gss_process_context_token routine 1455 has not been included in the Java bindings specification. The 1456 corresponding functionality of gss_delete_sec_context has also been 1457 modified to not return any peer tokens. This has been proposed in 1458 accordance to the recommendations stated in the RFC 2078 update 1459 draft. GSSContext does offer the functionality of destroying the 1460 locally-stored context information. 1462 5.5. MessageProp class 1464 This helper class is used in the per-message operations on the 1465 context. An instance of this class is created by the application and 1466 then passed into the per-message calls. In some cases, the 1467 application conveys information to the GSS-API implementation through 1468 this object and in other cases the GSS-API returns information to the 1469 application by setting it in this object. See the description of the 1470 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1471 GSSContext interfaces for details. 1473 5.6. GSSException class 1475 Exceptions are used in the Java bindings to signal fatal errors to 1476 the calling applications. This replaces the major and minor codes 1477 used in the C-bindings specification as a method of signaling 1478 failures. The GSSException class handles both minor and major codes, 1479 as well as their translation into textual representation. All GSS- 1480 API methods are declared as throwing this exception. 1482 GSS-API Java Bindings October 1999 1484 RFC 2078 Routine Function Section 1486 gss_display_status Retrieve textual 6.8.5, 6.8.6, 1487 representation of error 6.8.8, 6.8.9 1488 codes. 1490 5.7. Oid class 1492 This utility class is used to represent Universal Object Identifiers 1493 and their associated operations. GSS-API uses object identifiers to 1494 distinguish between security mechanisms and name types. This class, 1495 aside from being used whenever an object identifier is needed, 1496 implements the following GSS-API functionality: 1498 RFC 2078 Routine Function Section 1500 gss_test_oid_set_member Determine if the specified oid 6.7.5 1501 is part of a set of oids. 1503 5.8. ChannelBinding class 1505 An instance of this class is used to specify channel binding 1506 information to the GSSContext object before the start of a security 1507 context establishment. The application may use a byte array to 1508 specify application data to be used in the channel binding as well as 1509 use instances of the InetAddress. InetAddress is currently the only 1510 address type defined within the Java platform and as such, it is the 1511 only one supported within the ChannelBinding class. Applications that 1512 use other types of addresses can include them as part of the 1513 application data. 1515 6. Detailed GSS-API Class Description 1517 This section lists a detailed description of all the public methods 1518 that each of the GSS-API classes and interfaces must provide. 1520 6.1. public class GSSManager 1522 The GSSManager is a concrete class that serves as a factory for three 1523 GSS interfaces: GSSName, GSSCredential, and GSSContext. It also 1525 GSS-API Java Bindings October 1999 1527 provides methods for applications to determine what mechanisms are 1528 available on the system and what nametypes these mechanisms support. 1530 The GSSManager class may be internally implemented as a modular 1531 provider based layer that follows some service provider specification 1532 to lookup underlying mechanism components. It provides the 1533 application with a method to set a preferred provider for any given 1534 mechanism. 1536 6.1.1. Example Code 1538 GSSManager mgr = new GSSManager(); 1540 // What mechs are available to us? 1541 Oid[] supportedMechs = mgr.getMechs(); 1543 // Set a preference for the provider to be used when support is need 1544 // for the mechanisms "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.2". 1545 // Assume this provider (called "Sun") has already been installed on 1546 // the system. 1548 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1549 Oid spnego = new Oid("1.3.6.1.5.5.2"); 1551 mgr.setProvider(krb, "Sun"); 1552 mgr.setProvider(spnego, "Sun"); 1554 // Add support for a new mechanism "1.3.6.1.5.5.1.1" that is 1555 // available from a specific provider being bundled with the 1556 // application. 1558 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1560 Provider prov = (Provider) (new com.foo.security.Provider()); 1562 mgr.setProvider(spkm1, prov); 1564 // What name types does this spkm implementation support? 1565 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1567 6.1.2. Constructors 1569 public GSSManager() 1571 GSS-API Java Bindings October 1999 1573 Constructor which instantiates a GSSManager for the application. 1575 6.1.3. setProvider 1577 public void setProvider(Oid mech, String provName) 1578 throws GSSException, java.security.NoSuchProviderException 1580 Sets the provider for the GSS-API to use internally when it needs 1581 components to support the indicated mechanism. 1583 If the GSSManager implementation does not support an SPI with a 1584 pluggable provider architecture it should throw a GSSException with 1585 the status code GSSException.UNAVAILABLE to indicate that the 1586 operation is unavailable. If the requested provider does not support 1587 the indicated mech then it should throw a GSSException with the 1588 status code GSSException.BAD_MECH. 1590 This call assumes that the provider defined by the string provName is 1591 already installed on the system either statically or dynamically 1592 using the Java Cryptography Architecture (JCA) specification. If it 1593 does not find the provider it should throw a NoSuchProviderException. 1595 Parameters: 1597 mech The mechanism for which the provider is being set 1599 provName The name of the provider that should be used whenever 1600 support is needed for mech. A value of null will 1601 remove any previous preference set by the application. 1603 6.1.4. setProvider 1605 public void setProvider(Oid mech, java.security.Provider p) 1606 throws GSSException 1608 Sets the provider for the GSS-API to use internally when it needs 1609 components to support the indicated mechanism. 1611 If the GSSManager implementation does not support an SPI with a 1612 pluggable provider architecture it should throw a GSSException with 1613 the status code GSSException.UNAVAILABLE to indicate that the 1614 operation is unavailable. If the requested provider does not support 1615 the indicated mech then it should throw a GSSException with the 1616 status code GSSException.BAD_MECH. 1618 GSS-API Java Bindings October 1999 1620 This provider need not be installed globally on the system at all. 1621 The application instantiates the provider and passes it to the 1622 instance of GSSManager through this method. 1624 Parameters: 1626 mech The mechanism for which the provider is being set 1628 p The provider instance to be used to implement the 1629 services for the specified mechanism. A value of null 1630 will remove any previous preference set by the 1631 application. 1633 6.1.5. getProvider 1635 public Provider getProvider(Oid mech) 1637 Returns the preferred Provider instance that the GSS-API would use 1638 when trying to instantiate elements for the indicated mechanism. 1640 6.1.6. getMechs 1642 public Oid[] getMechs() 1644 Returns an array of Oid objects indicating mechanisms available to 1645 GSS-API callers. A "null" value is returned when no mechanism are 1646 available (an example of this would be when mechanism are dynamically 1647 configured, and currently no mechanisms are installed). 1649 6.1.7. getNamesForMech 1651 public Oid[] getNamesForMech(Oid mech) 1652 throws GSSException 1654 Returns name type Oid's supported by the specified mechanism. 1656 Parameters: 1658 mech The Oid object for the mechanism to query. 1660 GSS-API Java Bindings October 1999 1662 6.1.8. getMechsForName 1664 public Oid[] getMechsForName(Oid nameType) 1666 Returns an array of Oid objects corresponding to the mechanisms that 1667 support the specific name type. "null" is returned when no 1668 mechanisms are found to support the specified name type. 1670 Parameters: 1672 nameType The Oid object for the name type. 1674 6.1.9. createName 1676 public GSSName createName(String nameStr, Oid nameSpace) 1677 throws GSSException 1679 Factory method to convert a contiguous string name from the specified 1680 namespace to an GSSName object. In general, the GSSName object 1681 created will not be an MN; two examples that are exceptions to this 1682 are when the namespace type parameter indicates NT_EXPORT_NAME or 1683 when the GSS-API implementation is not multi-mechanism. 1685 Parameters: 1687 nameStr The string representing a printable form of the name 1688 to create. 1690 nameType The Oid specifying the namespace of the printable name 1691 supplied. Note that nameType serves to describe and 1692 qualify the interpretation of the input nameStr, it 1693 does not necessarily imply a type for the output 1694 GSSName implementation. "null" value can be used to 1695 specify that a mechanism specific default printable 1696 syntax should be assumed by each mechanism that 1697 examines nameStr. 1699 6.1.10. createName 1701 public GSSName createName(byte name[], Oid nameType) 1702 throws GSSException 1704 Factory method to convert a contiguous byte array containing a name 1706 GSS-API Java Bindings October 1999 1708 from the specified namespace to an GSSName object. In general, the 1709 GSSName object created will not be an MN; two examples that are 1710 exceptions to this are when the namespace type parameter indicates 1711 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1712 mechanism. 1714 Parameters: 1716 name The byte array containing the name to create. 1718 nameType The Oid specifying the namespace of the name supplied 1719 in the byte array. Note that nameType serves to 1720 describe and qualify the interpretation of the input 1721 name byte array, it does not necessarily imply a type 1722 for the output GSSName implementation. "null" value 1723 can be used to specify that a mechanism specific 1724 default syntax should be assumed by each mechanism 1725 that examines the byte array. 1727 6.1.11. createName 1729 public GSSName createName(String nameStr, Oid nameType, 1730 Oid mechType) throws GSSException 1732 Factory method to convert a contiguous string name from the specified 1733 namespace to an GSSName object that is a mechanism name (MN). In 1734 other words, this method is a utility that does the equivalent of two 1735 steps: the createName described in 6.1.7 and then also the 1736 GSSName.canonicalize() described in 6.2.5. 1738 Parameters: 1740 nameStr The string representing a printable form of the name 1741 to create. 1743 nameType The Oid specifying the namespace of the printable name 1744 supplied. Note that nameType serves to describe and 1745 qualify the interpretation of the input nameStr, it 1746 does not necessarily imply a type for the output 1747 GSSName implementation. "null" value can be used to 1748 specify that a mechanism specific default printable 1749 syntax should be assumed when the mechanism examines 1750 nameStr. 1752 mechType Oid specifying the mechanism for which this name 1753 should be created. 1755 GSS-API Java Bindings October 1999 1757 6.1.12. createName 1759 public createName(byte name[], Oid nameType, Oid mechType) 1760 throws GSSException 1762 Factory method to convert a contiguous byte array containing a name 1763 from the specified namespace to an GSSName object that is an MN. In 1764 other words, this method is a utility that does the equivalent of two 1765 steps: the createName described in 6.1.8 and then also the 1766 GSSName.canonicalize() described in 6.2.5. 1768 Parameters: 1770 name The byte array representing the name to create. 1772 nameType The Oid specifying the namespace of the name supplied 1773 in the byte array. Note that nameType serves to 1774 describe and qualify the interpretation of the input 1775 name byte array, it does not necessarily imply a type 1776 for the output GSSName implementation. "null" value 1777 can be used to specify that a mechanism specific 1778 default syntax should be assumed by each mechanism 1779 that examines the byte array. 1781 mechType Oid specifying the mechanism for which this name 1782 should be created. 1784 6.1.13. createCredential 1786 public GSSCredential createCredential (int usage) 1787 throws GSSException 1789 Factory method for acquiring default credentials. This will cause 1790 the GSS-API to use system specific defaults for the set of 1791 mechanisms, name, and an INDEFINITE lifetime. 1793 Parameters: 1795 usage The intended usage for this credential object. The 1796 value of this parameter must be one of: 1797 GSSCredential.ACCEPT_AND_INITIATE, 1798 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1800 6.1.14. createCredential 1802 public GSSCredential createCredential (GSSName aName, 1804 GSS-API Java Bindings October 1999 1806 int lifetime, Oid mechOid, int usage) 1807 throws GSSException 1809 Factory method for acquiring a single mechanism credential. 1811 Parameters: 1813 aName Name of the principal for whom this credential is to 1814 be acquired. Use "null" to specify the default 1815 principal. 1817 lifetime The number of seconds that credentials should remain 1818 valid. Use GSSCredential.INDEFINITE to request that 1819 the credentials have the maximum permitted lifetime. 1821 mechOid The oid of the desired mechanism. Use "(Oid) null" to 1822 request the default mechanism(s). 1824 usage The intended usage for this credential object. The 1825 value of this parameter must be one of: 1826 GSSCredential.ACCEPT_AND_INITIATE, 1827 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1829 6.1.15. createCredential 1831 public GSSCredential createCredential(GSSName aName, 1832 int lifetime, Oid mechs[], int usage) 1833 throws GSSException 1835 Factory method for acquiring credentials over a set of mechanisms. 1836 Acquires credentials for each of the mechanisms specified in the 1837 array called mechs. To determine the list of mechanisms' for which 1838 the acquisition of credentials succeeded, the caller should use the 1839 GSSCredential.getMechs() method. 1841 Parameters: 1843 aName Name of the principal for whom this credential is to 1844 be acquired. Use "null" to specify the default 1845 principal. 1847 lifetime The number of seconds that credentials should remain 1848 valid. Use GSSCredential.INDEFINITE to request that 1849 the credentials have the maximum permitted lifetime. 1851 mechOid The array of mechanisms over which the credential is 1852 to be acquired. Use "(Oid[]) null" for requesting a 1854 GSS-API Java Bindings October 1999 1856 system specific default set of mechanisms. 1858 usage The intended usage for this credential object. The 1859 value of this parameter must be one of: 1860 GSSCredential.ACCEPT_AND_INITIATE, 1861 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1863 6.1.16. createContext 1865 public GSSContext createContext(GSSName peer, Oid mechOid, 1866 GSSCredential myCred, int lifetime) 1867 throws GSSException 1869 Factory method for creating a context on the initiator's side. 1870 Context flags may be modified through the mutator methods prior to 1871 calling GSSContext.initSecContext(). 1873 Parameters: 1875 peer Name of the target peer. 1877 mechOid Oid of the desired mechanism. Use "(Oid) null" to 1878 request default mechanism. 1880 myCred Credentials of the initiator. Use "null" to act as a 1881 default initiator principal. 1883 lifetime The request lifetime, in seconds, for the credential. 1885 6.1.17. createContext 1887 public GSSContext createContext(GSSCredential myCred) 1888 throws GSSException 1890 Factory method for creating a context on the acceptor' side. The 1891 context's properties will be determined from the input token supplied 1892 to the accept method. 1894 Parameters: 1896 myCred Credentials for the acceptor. Use "null" to act as a 1897 default acceptor principal. 1899 GSS-API Java Bindings October 1999 1901 6.1.18. createContext 1903 public GSSContext createContext(byte [] interProcessToken) 1904 throws GSSException 1906 Factory method for creating a previously exported context. The 1907 context properties will be determined from the input token and can't 1908 be modified through the set methods. 1910 Parameters: 1912 interProcessToken 1913 The token previously emitted from the export method. 1915 6.2. public interface GSSName 1917 This interface encapsulates a single GSS-API principal entity. 1918 Different name formats and their definitions are identified with 1919 universal Object Identifiers (Oids). The format of the names can be 1920 derived based on the unique oid of its namespace type. 1922 6.2.1. Example Code 1924 Included below are code examples utilizing the GSSName interface. 1925 The code below creates a GSSName, converts it to a mechanism name 1926 (MN), performs a comparison, obtains a printable representation of 1927 the name, exports it and then re-imports to obtain a new GSSName. 1929 GSSManager mgr = new GSSManager(); 1931 // create a host based service name 1932 GSSName name = mgr.createName("service@host", 1933 GSSName.NT_HOSTBASED_SERVICE); 1935 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 1937 GSSName mechName = name.canonicalize(krb5); 1939 // the above two steps are equivalent to the following 1940 GSSName mechName = mgr.createName("service@host", 1941 GSSName.NT_HOSTBASED_SERVICE, krb5); 1943 // perform name comparison 1944 if (name.equals(mechName)) 1946 GSS-API Java Bindings October 1999 1948 print("Names are equals."); 1950 // obtain textual representation of name and its printable 1951 // name type 1952 print(mechName.toString() + 1953 mechName.getStringNameType().toString()); 1955 // export and re-import the name 1956 byte [] exportName = mechName.export(); 1958 // create a new name object from the exported buffer 1959 GSSName newName = mgr.createName(exportName, 1960 GSSName.NT_EXPORT_NAME); 1962 6.2.2. Static Constants 1964 public static final Oid NT_HOSTBASED_SERVICE 1966 Oid indicating a host-based service name form. It is used to 1967 represent services associated with host computers. This name form is 1968 constructed using two elements, "service" and "hostname", as follows: 1970 service@hostname 1972 Values for the "service" element are registered with the IANA. It 1973 represents the following value: { 1(iso), 3(org), 6(dod), 1974 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) } 1976 public static final Oid NT_USER_NAME 1978 Name type to indicate a named user on a local system. It represents 1979 the following value: { iso(1) member-body(2) United States(840) 1980 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 1982 public static final Oid NT_MACHINE_UID_NAME 1984 Name type to indicate a numeric user identifier corresponding to a 1985 user on a local system. (e.g. Uid). It represents the following 1986 value: { iso(1) member-body(2) United States(840) mit(113554) 1987 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 1989 public static final Oid NT_STRING_UID_NAME 1991 GSS-API Java Bindings October 1999 1993 Name type to indicate a string of digits representing the numeric 1994 user identifier of a user on a local system. It represents the 1995 following value: { iso(1) member-body(2) United States(840) 1996 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 1998 public static final Oid NT_ANONYMOUS 2000 Name type for representing an anonymous entity. It represents the 2001 following value: { 1(iso), 3(org), 6(dod), 1(internet), 5(security), 2002 6(nametypes), 3(gss-anonymous-name) } 2004 public static final Oid NT_EXPORT_NAME 2006 Name type used to indicate an exported name produced by the export 2007 method. It represents the following value: { 1(iso), 3(org), 6(dod), 2008 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) } 2010 6.2.3. equals 2012 public boolean equals(GSSName another) throws GSSException 2014 Compares two GSSName objects to determine whether they refer to the 2015 same entity. This method may throw a GSSException when the names 2016 cannot be compared. If either of the names represents an anonymous 2017 entity, the method will return "false". 2019 Parameters: 2021 another GSSName object to compare with. 2023 6.2.4. equals 2025 public boolean equals(Object another) 2027 A variation of the equals method described in 6.2.3 that is provided 2028 to override the Object.equals() method that the implementing class 2029 will inherit. The behaviour is exactly the same as that in 6.2.3 2030 except that no GSSException is thrown; instead, false will be 2031 returned in the situation where an error occurs. 2033 Parameters: 2035 another GSSName object to compare with. 2037 GSS-API Java Bindings October 1999 2039 6.2.5. canonicalize 2041 public GSSName canonicalize(Oid mechOid) throws GSSException 2043 Creates a mechanism name (MN) from an arbitrary internal name. This 2044 is equivalent to using the factory methods described in 6.1.9 or 2045 6.1.10 that take the mechanism name as one of their parameters. 2047 Parameters: 2049 mechOid The oid for the mechanism for which the canonical form 2050 of the name is requested. 2052 6.2.6. export 2054 public byte[] export() throws GSSException 2056 Returns a canonical contiguous byte representation of a mechanism 2057 name (MN), suitable for direct, byte by byte comparison by 2058 authorization functions. If the name is not an MN, implementations 2059 may throw a GSSException with the NAME_NOT_MN status code. If an 2060 implementation chooses not to throw an exception, it should use some 2061 system specific default mechanism to canonicalize the name and then 2062 export it. The format of the header of the output buffer is 2063 specified in RFC 2078. 2065 6.2.7. toString 2067 public String toString() 2069 Returns a textual representation of the GSSName object. To retrieve 2070 the printed name format, which determines the syntax of the returned 2071 string, the getStringNameType method can be used. 2073 6.2.8. getStringNameType 2075 public Oid getStringNameType() throws GSSException 2077 Returns the oid representing the type of name returned through the 2078 toString method. Using this oid, the syntax of the printable name 2079 can be determined. 2081 GSS-API Java Bindings October 1999 2083 6.2.9. isAnonymous 2085 public boolean isAnonymous() 2087 Tests if this name object represents an anonymous entity. Returns 2088 "true" if this is an anonymous name. 2090 6.2.10. isMN 2092 public boolean isMN() 2094 Tests if this name object contains only one mechanism element and is 2095 thus a mechanism name as defined by RFC 2078. 2097 6.3. public interface GSSCredential implements Cloneable 2099 This interface encapsulates the GSS-API credentials for an entity. A 2100 credential contains all the necessary cryptographic information to 2101 enable the creation of a context on behalf of the entity that it 2102 represents. It may contain multiple, distinct, mechanism specific 2103 credential elements, each containing information for a specific 2104 security mechanism, but all referring to the same entity. 2106 A credential may be used to perform context initiation, acceptance, 2107 or both. 2109 GSS-API implementations must impose a local access-control policy on 2110 callers to prevent unauthorized callers from acquiring credentials to 2111 which they are not entitled. GSS-API credential creation is not 2112 intended to provide a "login to the network" function, as such a 2113 function would involve the creation of new credentials rather than 2114 merely acquiring a handle to existing credentials. Such functions, 2115 if required, should be defined in implementation-specific extensions 2116 to the API. 2118 If credential acquisition is time-consuming for a mechanism, the 2119 mechanism may choose to delay the actual acquisition until the 2120 credential is required (e.g. by GSSContext). Such mechanism- 2121 specific implementation decisions should be invisible to the calling 2122 application; thus the query methods immediately following the 2123 creation of a credential object must return valid credential data, 2124 and may therefore incur the overhead of a deferred credential 2125 acquisition. 2127 Applications will create a credential object passing the desired 2129 GSS-API Java Bindings October 1999 2131 parameters. The application can then use the query methods to obtain 2132 specific information about the instantiated credential object 2133 (equivalent to the gss_inquire routines). When the credential is no 2134 longer needed, the application should call the dispose (equivalent to 2135 gss_release_cred) method to release any resources held by the 2136 credential object and to destroy any cryptographically sensitive 2137 information. 2139 Classes implementing this interface also implement the Cloneable 2140 interface. This indicates the the class will support the clone() 2141 method that will allow the creation of duplicate credentials. This 2142 is useful when called just before the add() call to retain a copy of 2143 the original credential. 2145 6.3.1. Example Code 2147 This example code demonstrates the creation of a GSSCredential 2148 implementation for a specific entity, querying of its fields, and its 2149 release when it is no longer needed. 2151 GSSManager mgr = new GSSManager(); 2153 // start by creating a name object for the entity 2154 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2156 // now acquire credentials for the entity 2157 GSSCredential cred = mgr.createCredential(name, 2158 GSSCredential.ACCEPT_ONLY); 2160 // display credential information - name, remaining lifetime, 2161 // and the mechanisms it has been acquired over 2162 print(cred.getName().toString()); 2163 print(cred.getRemainingLifetime()); 2165 Oid [] mechs = cred.getMechs(); 2166 if (mechs != null) { 2167 for (int i = 0; i < mechs.length; i++) 2168 print(mechs[i].toString()); 2169 } 2171 // release system resources held by the credential 2172 cred.dispose(); 2174 GSS-API Java Bindings October 1999 2176 6.3.2. Static Constants 2178 public static final int INITIATE_AND_ACCEPT 2180 Credential usage flag requesting that it be able to be used for both 2181 context initiation and acceptance. 2183 public static final int INITIATE_ONLY 2185 Credential usage flag requesting that it be able to be used for 2186 context initiation only. 2188 public static final int ACCEPT_ONLY 2190 Credential usage flag requesting that it be able to be used for 2191 context acceptance only. 2193 public static final int INDEFINITE 2195 A lifetime constant representing indefinite credential lifetime. 2196 This value must be set to the maximum integer value in Java - 2197 Integer.MAX_VALUE. 2199 6.3.3. dispose 2201 public void dispose() throws GSSException 2203 Releases any sensitive information that the GSSCredential object may 2204 be containing. Applications should call this method as soon as the 2205 credential is no longer needed to minimize the time any sensitive 2206 information is maintained. 2208 6.3.4. getName 2210 public GSSName getName() throws GSSException 2212 Retrieves the name of the entity that the credential asserts. 2214 6.3.5. getName 2216 public GSSName getName(Oid mechOID) throws GSSException 2218 GSS-API Java Bindings October 1999 2220 Retrieves a mechanism name of the entity that the credential asserts. 2221 Equivalent to calling canonicalize() on the name returned by 7.3.3. 2223 Parameters: 2225 mechOID The mechanism for which information should be 2226 returned. 2228 6.3.6. getRemainingLifetime 2230 public int getRemainingLifetime() throws GSSException 2232 Returns the remaining lifetime in seconds for a credential. The 2233 remaining lifetime is the minimum lifetime for any of the underlying 2234 credential mechanisms. A return value of GSSCredential.INDEFINITE 2235 indicates that the credential does not expire. A return value of 0 2236 indicates that the credential is already expired. 2238 6.3.7. getRemainingInitLifetime 2240 public int getRemainingInitLifetime(Oid mech) throws GSSException 2242 Returns the remaining lifetime is seconds for the credential to 2243 remain capable of initiating security contexts under the specified 2244 mechanism. A return value of GSSCredential.INDEFINITE indicates that 2245 the credential does not expire for context initiation. A return 2246 value of 0 indicates that the credential is already expired. 2248 Parameters: 2250 mechOID The mechanism for which information should be 2251 returned. 2253 6.3.8. getRemainingAcceptLifetime 2255 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2257 Returns the remaining lifetime is seconds for the credential to 2258 remain capable of accepting security contexts under the specified 2259 mechanism. A return value of GSSCredential.INDEFINITE indicates that 2260 the credential does not expire for context acceptance. A return 2261 value of 0 indicates that the credential is already expired. 2263 Parameters: 2265 GSS-API Java Bindings October 1999 2267 mechOID The mechanism for which information should be 2268 returned. 2270 6.3.9. getUsage 2272 public int getUsage() throws GSSException 2274 Returns the credential usage flag. The return value will be one of 2275 GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or 2276 GSSCredential.INITIATE_AND_ACCEPT. 2278 6.3.10. getUsage 2280 public int getUsage(Oid mechOID) throws GSSException 2282 Returns the credential usage flag for the specified credential 2283 mechanism. The return value will be one of 2284 GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or 2285 GSSCredential.INITIATE_AND_ACCEPT. 2287 Parameters: 2289 mechOID The mechanism for which information should be 2290 returned. 2292 6.3.11. getMechs 2294 public Oid[] getMechs() throws GSSException 2296 Returns an array of mechanisms supported by this credential. 2298 6.3.12. add 2300 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2301 Oid mech, int usage) throws GSSException 2303 Adds a mechanism specific credential-element to an existing 2304 credential. This method allows the construction of credentials one 2305 mechanism at a time. 2307 This routine is envisioned to be used mainly by context acceptors 2308 during the creation of acceptance credentials which are to be used 2309 with a variety of clients using different security mechanisms. 2311 GSS-API Java Bindings October 1999 2313 This routine adds the new credential element "in-place". To add the 2314 element in a new credential, first call clone() to obtain a copy of 2315 this credential, then call its add() method. 2317 Parameters: 2319 aName Name of the principal for whom this credential is to 2320 be acquired. Use "null" to specify the default 2321 principal. 2323 initLifetime 2324 The number of seconds that credentials should remain 2325 valid for initiating of security contexts. Use 2326 GSSCredential.INDEFINITE to request that the 2327 credentials have the maximum permitted lifetime. 2329 acceptLifetime 2330 The number of seconds that credentials should remain 2331 valid for accepting of security contexts. Use 2332 GSSCredential.INDEFINITE to request that the 2333 credentials have the maximum permitted lifetime. 2335 mechOid The mechanisms over which the credential is to be 2336 acquired. 2338 usage The intended usage for this credential object. The 2339 value of this parameter must be one of: 2340 GSSCredential.ACCEPT_AND_INITIATE, 2341 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 2343 6.3.13. equals 2345 public boolean equals(Object another) 2347 Tests if this GSSCredential refers to the same entity as the supplied 2348 object. The two credentials must be acquired over the same 2349 mechanisms and must refer to the same principal. Returns "true" if 2350 the two GSSCredentials refer to the same entity; "false" otherwise. 2352 Parameters: 2354 another Another GSSCredential object for comparison. 2356 GSS-API Java Bindings October 1999 2358 6.4. public interface GSSContext 2360 This interface encapsulates the GSS-API security context and provides 2361 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2362 available over the context. Security contexts are established 2363 between peers using locally acquired credentials. Multiple contexts 2364 may exist simultaneously between a pair of peers, using the same or 2365 different set of credentials. GSS-API functions in a manner 2366 independent of the underlying transport protocol and depends on its 2367 calling application to transport its tokens between peers. 2369 Before the context establishment phase is initiated, the context 2370 initiator may request specific characteristics desired of the 2371 established context. These can be set using the set methods. After 2372 the context is established, the caller can check the actual 2373 characteristic and services offered by the context using the query 2374 methods. 2376 The context establishment phase begins with the first call to the 2377 init method by the context initiator. During this phase the 2378 initSecContext and acceptSecContext methods will produce GSS-API 2379 authentication tokens which the calling application needs to send to 2380 its peer. If an error occurs at any point, an exception will get 2381 thrown and the code will start executing in a catch block. If not, 2382 the normal flow of code continues and the application can make a call 2383 to the isEstablished() method. If this method returns false it 2384 indicates that a token is needed from its peer in order to continue 2385 the context establishment phase. A return value of true signals that 2386 the local end of the context is established. This may still require 2387 that a token be sent to the peer, if one is produced by GSS-API. 2388 During the context establishment phase, the isProtReady() method may 2389 be called to determine if the context can be used for the per-message 2390 operations. This allows applications to use per-message operations 2391 on contexts which aren't fully established. 2393 After the context has been established or the isProtReady() method 2394 returns "true", the query routines can be invoked to determine the 2395 actual characteristics and services of the established context. The 2396 application can also start using the per-message methods of wrap and 2397 getMIC to obtain cryptographic operations on application supplied 2398 data. 2400 When the context is no longer needed, the application should call 2401 dispose to release any system resources the context may be using. 2403 GSS-API Java Bindings October 1999 2405 6.4.1. Example Code 2407 The example code presented below demonstrates the usage of the 2408 GSSContext interface for the initiating peer. Different operations 2409 on the GSSContext object are presented, including: object 2410 instantiation, setting of desired flags, context establishment, query 2411 of actual context flags, per-message operations on application data, 2412 and finally context deletion. 2414 GSSManager mgr = new GSSManager(); 2416 // start by creating the name for a service entity 2417 GSSName targetName = mgr.createName("service@host", 2418 GSSName.NT_HOSTBASED_SERVICE); 2420 // create a context using default credentials for the above entity 2421 // and the implementation specific default mechanism 2422 GSSContext context = mgr.createContext(targetName, 2423 null, /* default mechanism */ 2424 null, /* default credentials */ 2425 GSSContext.INDEFINITE); 2427 // set desired context options - all others are false by default 2428 context.requestConf(true); 2429 context.requestMutualAuth(true); 2430 context.requestReplayDet(true); 2431 context.requestSequenceDet(true); 2433 // establish a context between peers - using byte arrays 2434 byte []inTok = new byte[0]; 2436 try { 2437 do { 2438 byte[] outTok = context.initSecContext(inTok, 0, 2439 inTok.length); 2441 // send the token if present 2442 if (outTok != null) 2443 sendToken(outTok); 2445 // check if we should expect more tokens 2446 if (context.isEstablished()) 2447 break; 2449 // another token expected from peer 2450 inTok = readToken(); 2452 GSS-API Java Bindings October 1999 2454 } while (true); 2456 } catch (GSSException e) { 2457 print("GSSAPI error: " + e.getMessage()); 2458 } 2460 // display context information 2461 print("Remaining lifetime in seconds = " + context.getLifetime()); 2462 print("Context mechanism = " + context.getMech().toString()); 2463 print("Initiator = " + context.getSrcName().toString()); 2464 print("Acceptor = " + context.getTargName().toString()); 2466 if (context.getConfState()) 2467 print("Confidentiality security service available"); 2469 if (context.getIntegState()) 2470 print("Integrity security service available"); 2472 // perform wrap on an application supplied message, appMsg, 2473 // using QOP = 0, and requesting privacy service 2474 byte [] appMsg ... 2476 MessageProp mProp = new MessageProp(0, true); 2478 byte []tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2480 if (mProp.getPrivacy()) 2481 print("Message protected with privacy."); 2483 sendToken(tok); 2485 // release the local-end of the context 2486 context.dispose(); 2488 6.4.2. Static Constants 2490 public static final int INDEFINITE 2492 A lifetime constant representing indefinite context lifetime. This 2493 value must be set to the maximum integer value in Java - 2494 Integer.MAX_VALUE. 2496 GSS-API Java Bindings October 1999 2498 6.4.3. initSecContext 2500 public byte[] initSecContext(byte inputBuf[], int offset, int len) 2501 throws GSSException 2503 Called by the context initiator to start the context creation 2504 process. This is equivalent to the stream based method except that 2505 the token buffers are handled as byte arrays instead of using stream 2506 objects. This method may return an output token which the 2507 application will need to send to the peer for processing by the 2508 accept call. "null" return value indicates that no token needs to be 2509 sent to the peer. The application can call isEstablished() to 2510 determine if the context establishment phase is complete for this 2511 peer. A return value of "false" from isEstablished() indicates that 2512 more tokens are expected to be supplied to the initSecContext() 2513 method. Note that it is possible that the initSecContext() method 2514 return a token for the peer, and isEstablished() return "true" also. 2515 This indicates that the token needs to be sent to the peer, but the 2516 local end of the context is now fully established. 2518 Upon completion of the context establishment, the available context 2519 options may be queried through the get methods. 2521 Parameters: 2523 inputBuf Token generated by the peer. This parameter is ignored 2524 on the first call. 2526 offset The offset within the inputBuf where the token begins. 2528 len The length of the token within the inputBuf (starting 2529 at the offset). 2531 6.4.3.1. Example Code 2533 // Create a new GSSContext implementation object. 2534 // GSSContext wrapper implements interface GSSContext. 2535 GSSContext context = mgr.createContext(...); 2537 byte []inTok = new byte[0]; 2539 try { 2541 do { 2542 byte[] outTok = context.initSecContext(inTok, 0, 2544 GSS-API Java Bindings October 1999 2546 inTok.length); 2548 // send the token if present 2549 if (outTok != null) 2550 sendToken(outTok); 2552 // check if we should expect more tokens 2553 if (context.isEstablished()) 2554 break; 2556 // another token expected from peer 2557 inTok = readToken(); 2558 } while (true); 2560 } catch (GSSException e) { 2561 print("GSSAPI error: " + e.getMessage()); 2562 } 2564 6.4.4. initSecContext 2566 public int initSecContext(InputStream inStream, 2567 OutputStream outStream) throws GSSException 2569 Called by the context initiator to start the context creation 2570 process. This is equivalent to the byte array based method. This 2571 method may write an output token to the outStream, which the 2572 application will need to send to the peer for processing by the 2573 accept call. 0 bytes written to the output stream indicate that no 2574 token needs to be sent to the peer. The application can call 2575 isEstablished() to determine if the context establishment phase is 2576 complete for this peer. A return value of "false" from isEstablished 2577 indicates that more tokens are expected to be supplied to the 2578 initSecContext method. Note that it is possible that the 2579 initSecContext() method return a token for the peer, and 2580 isEstablished() return "true" also. This indicates that the token 2581 needs to be sent to the peer, but the local end of the context is now 2582 fully established. 2584 The GSS-API authentication tokens contain a definitive start and end. 2585 This method will attempt to read one of these tokens per invocation, 2586 and may block on the stream if only part of the token is available. 2588 Upon completion of the context establishment, the available context 2589 options may be queried through the get methods. 2591 GSS-API Java Bindings October 1999 2593 Parameters: 2595 inStream Contains the token generated by the peer. This 2596 parameter is ignored on the first call. 2598 outStream Output stream where the output token will be written. 2599 During the final stage of context establishment, there 2600 may be no bytes written. 2602 6.4.4.1. Example Code 2604 // Create a new GSSContext implementation object. 2605 // GSSContext wrapper implements interface GSSContext. 2606 GSSContext context = mgr.createContext(...); 2608 // use standard java.io stream objects 2609 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2610 ByteArrayInputStream is = null; 2612 try { 2614 do { 2615 context.initSecContext(is, os); 2617 // send token if present 2618 if (os.size() > 0) 2619 sendToken(os); 2621 // check if we should expect more tokens 2622 if (context.isEstablished()) 2623 break; 2625 // another token expected from peer 2626 is = recvToken(); 2628 } while (true); 2630 } catch (GSSException e) { 2631 print("GSSAPI error: " + e.getMessage()); 2632 } 2634 GSS-API Java Bindings October 1999 2636 6.4.5. acceptSecContext 2638 public byte[] acceptSecContext(byte inTok[], int offset, int len) 2639 throws GSSException 2641 Called by the context acceptor upon receiving a token from the peer. 2642 This call is equivalent to the stream based method except that the 2643 token buffers are handled as byte arrays instead of using stream 2644 objects. 2646 This method may return an output token which the application will 2647 need to send to the peer for further processing by the init call. 2648 "null" return value indicates that no token needs to be sent to the 2649 peer. The application can call isEstablished() to determine if the 2650 context establishment phase is complete for this peer. A return 2651 value of "false" from isEstablished() indicates that more tokens are 2652 expected to be supplied to this method. 2654 Note that it is possible that acceptSecContext() return a token for 2655 the peer, and isEstablished() return "true" also. This indicates 2656 that the token needs to be sent to the peer, but the local end of the 2657 context is now fully established. 2659 Upon completion of the context establishment, the available context 2660 options may be queried through the get methods. 2662 Parameters: 2664 inTok Token generated by the peer. 2666 offset The offset within the inTok where the token begins. 2668 len The length of the token within the inTok (starting at 2669 the offset). 2671 6.4.5.1. Example Code 2673 // acquire server credentials 2674 GSSCredential server = mgr.createCredential(...); 2676 // create acceptor GSS-API context fromthe default provider 2677 GSSContext context = mgr.createContext(server, null); 2679 try { 2680 do { 2681 byte [] inTok = readToken(); 2683 GSS-API Java Bindings October 1999 2685 byte []outTok = context.acceptSecContext(inTok, 0, 2686 inTok.length); 2688 // possibly send token to peer 2689 if (outTok != null) 2690 sendToken(outTok); 2692 // check if local context establishment is complete 2693 if (context.isEstablished()) 2694 break; 2695 } while (true); 2697 } catch (GSSException e) { 2698 print("GSS-API error: " + e.getMessage()); 2699 } 2701 6.4.6. acceptSecContext 2703 public void acceptSecContext(InputStream inStream, 2704 OutputStream outStream) throws GSSException 2706 Called by the context acceptor upon receiving a token from the peer. 2707 This call is equivalent to the byte array method. It may write an 2708 output token to the outStream, which the application will need to 2709 send to the peer for processing by its initSecContext method. 0 bytes 2710 written to the output stream indicate that no token needs to be sent 2711 to the peer. The application can call isEstablished() to determine 2712 if the context establishment phase is complete for this peer. A 2713 return value of "false" from isEstablished() indicates that more 2714 tokens are expected to be supplied to this method. 2716 Note that it is possible that acceptSecContext() return a token for 2717 the peer, and isEstablished() return "true" also. This indicates 2718 that the token needs to be sent to the peer, but the local end of the 2719 context is now fully established. 2721 The GSS-API authentication tokens contain a definitive start and end. 2722 This method will attempt to read one of these tokens per invocation, 2723 and may block on the stream if only part of the token is available. 2725 Upon completion of the context establishment, the available context 2726 options may be queried through the get methods. 2728 Parameters: 2730 inStream Contains the token generated by the peer. 2732 GSS-API Java Bindings October 1999 2734 outStream Output stream where the output token will be written. 2735 During the final stage of context establishment, there 2736 may be no bytes written. 2738 6.4.6.1. Example Code 2740 // acquire server credentials 2741 GSSCredential server = mgr.createCredential(...); 2743 // create acceptor GSS-API context fromthe default provider 2744 GSSContext context = mgr.createContext(server, null); 2746 // use standard java.io stream objects 2747 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2748 ByteArrayInputStream is = null; 2750 try { 2751 do { 2753 is = recvToken(); 2755 context.acceptSecContext(is, os); 2757 // possibly send token to peer 2758 if (os.size() > 0) 2759 sendToken(os); 2761 // check if local context establishment is complete 2762 if (context.isEstablished()) 2763 break; 2764 } while (true); 2766 } catch (GSSException e) { 2767 print("GSS-API error: " + e.getMessage()); 2768 } 2770 6.4.7. isEstablished 2772 public boolean isEstablished() 2774 Used during context establishment to determine the state of the 2775 context. Returns "true" if this is a fully established context on 2776 the caller's side and no more tokens are needed from the peer. 2778 GSS-API Java Bindings October 1999 2780 Should be called after a call to initSecContext() or 2781 acceptSecContext() when no GSSException is thrown. 2783 6.4.8. dispose 2785 public void dispose() throws GSSException 2787 Releases any system resources and cryptographic information stored in 2788 the context object. This will invalidate the context. 2790 6.4.9. getWrapSizeLimit 2792 public int getWrapSizeLimit(int qop, boolean confReq, 2793 int maxTokenSize) throws GSSException 2795 Returns the maximum message size that, if presented to the wrap 2796 method with the same confReq and qop parameters, will result in an 2797 output token containing no more than the maxTokenSize bytes. 2799 This call is intended for use by applications that communicate over 2800 protocols that impose a maximum message size. It enables the 2801 application to fragment messages prior to applying protection. 2803 GSS-API implementations are recommended but not required to detect 2804 invalid QOP values when getWrapSizeLimit is called. This routine 2805 guarantees only a maximum message size, not the availability of 2806 specific QOP values for message protection. 2808 Successful completion of this call does not guarantee that wrap will 2809 be able to protect a message of the computed length, since this 2810 ability may depend on the availability of system resources at the 2811 time that wrap is called. However, if the implementation itself 2812 imposes an upper limit on the length of messages that may be 2813 processed by wrap, the implementation should not return a value that 2814 is greater than this length. 2816 Parameters: 2818 qop Indicates the level of protection wrap will be asked 2819 to provide. 2821 confReq Indicates if wrap will be asked to provide privacy 2822 service. 2824 maxTokenSize 2825 The desired maximum size of the token emitted by wrap. 2827 GSS-API Java Bindings October 1999 2829 6.4.10. wrap 2831 public byte[] wrap(byte inBuf[], int offset, int len, 2832 MessageProp msgProp) throws GSSException 2834 Applies per-message security services over the established security 2835 context. The method will return a token with a cryptographic MIC and 2836 may optionally encrypt the specified inBuf. This method is 2837 equivalent in functionality to its stream counterpart. The returned 2838 byte array will contain both the MIC and the message. 2840 The MessageProp object is instantiated by the application and used to 2841 specify a QOP value which selects cryptographic algorithms, and a 2842 privacy service to optionally encrypt the message. The underlying 2843 mechanism that is used in the call may not be able to provide the 2844 privacy service. It sets the actual privacy service that it does 2845 provide in this MessageProp object which the caller should then query 2846 upon return. If the mechanism is not able to provide the requested 2847 QOP, it throws a GSSException with the BAD_QOP code. 2849 Since some application-level protocols may wish to use tokens emitted 2850 by wrap to provide "secure framing", implementations should support 2851 the wrapping of zero-length messages. 2853 The application will be responsible for sending the token to the 2854 peer. 2856 Parameters: 2858 inBuf Application data to be protected. 2860 offset The offset within the inBuf where the data begins. 2862 len The length of the data within the inBuf (starting at 2863 the offset). 2865 msgProp Instance of MessageProp that is used by the 2866 application to set the desired QOP and privacy state. 2867 Set the desired QOP to 0 to request the default QOP. 2868 Upon return from this method, this object will contain 2869 the the actual privacy state that was applied to the 2870 message by the underlying mechanism. 2872 6.4.11. wrap 2874 public void wrap(InputStream inStream, OutputStream outStream, 2875 MessageProp msgProp) throws GSSException 2877 GSS-API Java Bindings October 1999 2879 Allows to apply per-message security services over the established 2880 security context. The method will produce a token with a 2881 cryptographic MIC and may optionally encrypt the message in inStream. 2882 The outStream will contain both the MIC and the message. 2884 The MessageProp object is instantiated by the application and used to 2885 specify a QOP value which selects cryptographic algorithms, and a 2886 privacy service to optionally encrypt the message. The underlying 2887 mechanism that is used in the call may not be able to provide the 2888 privacy service. It sets the actual privacy service that it does 2889 provide in this MessageProp object which the caller should then query 2890 upon return. If the mechanism is not able to provide the requested 2891 QOP, it throws a GSSException with the BAD_QOP code. 2893 Since some application-level protocols may wish to use tokens emitted 2894 by wrap to provide "secure framing", implementations should support 2895 the wrapping of zero-length messages. 2897 The application will be responsible for sending the token to the 2898 peer. 2900 Parameters: 2902 inStream Input stream containing the application data to be 2903 protected. 2905 outStream The output stream to write the protected message to. 2906 The application is responsible for sending this to the 2907 other peer for processing in its unwrap method. 2909 msgProp Instance of MessageProp that is used by the 2910 application to set the desired QOP and privacy state. 2911 Set the desired QOP to 0 to request the default QOP. 2912 Upon return from this method, this object will contain 2913 the the actual privacy state that was applied to the 2914 message by the underlying mechanism. 2916 6.4.12. unwrap 2918 public byte [] unwrap(byte[] inBuf, int offset, int len, 2919 MessageProp msgProp) throws GSSException 2921 Used by the peer application to process tokens generated with the 2922 wrap call. This call is equal in functionality to its stream 2923 counterpart. The method will return the message supplied in the peer 2924 application to the wrap call, verifying the embedded MIC. 2926 GSS-API Java Bindings October 1999 2928 The MessageProp object is instantiated by the application and is used 2929 by the underlying mechanism to return information to the caller such 2930 as the QOP, whether confidentiality was applied to the message, and 2931 other supplementary message state information. 2933 Since some application-level protocols may wish to use tokens emitted 2934 by wrap to provide "secure framing", implementations should support 2935 the wrapping and unwrapping of zero-length messages. 2937 Parameters: 2939 inBuf GSS-API wrap token received from peer. 2941 offset The offset within the inBuf where the token begins. 2943 len The length of the token within the inBuf (starting at 2944 the offset). 2946 msgProp Upon return from the method, this object will contain 2947 the applied QOP, the privacy state of the message, and 2948 supplementary information described in 4.12.3 stating 2949 whether the token was a duplicate, old, out of 2950 sequence or arriving after a gap. 2952 6.4.13. unwrap 2954 public void unwrap(InputStream inStream, OutputStream outStream, 2955 MessageProp msgProp) throws GSSException 2957 Used by the peer application to process tokens generated with the 2958 wrap call. This call is equal in functionality to its byte array 2959 counterpart. It will produce the message supplied in the peer 2960 application to the wrap call, verifying the embedded MIC. 2962 The MessageProp object is instantiated by the application and is used 2963 by the underlying mechanism to return information to the caller such 2964 as the QOP, whether confidentiality was applied to the message, and 2965 other supplementary message state information. 2967 Since some application-level protocols may wish to use tokens emitted 2968 by wrap to provide "secure framing", implementations should support 2969 the wrapping and unwrapping of zero-length messages. 2971 Parameters: 2973 inStream Input stream containing the GSS-API wrap token 2974 received from the peer. 2976 GSS-API Java Bindings October 1999 2978 outStream The output stream to write the application message to. 2980 msgProp Upon return from the method, this object will contain 2981 the applied QOP, the privacy state of the message, and 2982 supplementary information described in 4.12.3 stating 2983 whether the token was a duplicate, old, out of 2984 sequence or arriving after a gap. 2986 6.4.14. getMIC 2988 public byte[] getMIC(byte []inMsg, int offset, int len, 2989 MessageProp msgProp) throws GSSException 2991 Returns a token containing a cryptographic MIC for the supplied 2992 message, for transfer to the peer application. Unlike wrap, which 2993 encapsulates the user message in the returned token, only the message 2994 MIC is returned in the output token. This method is identical in 2995 functionality to its stream counterpart. 2997 Note that privacy can only be applied through the wrap call. 2999 Since some application-level protocols may wish to use tokens emitted 3000 by getMIC to provide "secure framing", implementations should support 3001 derivation of MICs from zero-length messages. 3003 Parameters: 3005 inMsg Message to generate MIC over. 3007 offset The offset within the inMsg where the token begins. 3009 len The length of the token within the inMsg (starting at 3010 the offset). 3012 msgProp Instance of MessageProp that is used by the 3013 application to set the desired QOP. Set the desired 3014 QOP to 0 in msgProp to request the default QOP. 3015 Alternatively pass in "null" for msgProp to request 3016 default QOP. 3018 6.4.15. getMIC 3020 public void getMIC(InputStream inStream, OutputStream outStream, 3021 MessageProp msgProp) throws GSSException 3023 Produces a token containing a cryptographic MIC for the supplied 3025 GSS-API Java Bindings October 1999 3027 message, for transfer to the peer application. Unlike wrap, which 3028 encapsulates the user message in the returned token, only the message 3029 MIC is produced in the output token. This method is identical in 3030 functionality to its byte array counterpart. 3032 Note that privacy can only be applied through the wrap call. 3034 Since some application-level protocols may wish to use tokens emitted 3035 by getMIC to provide "secure framing", implementations should support 3036 derivation of MICs from zero-length messages. 3038 Parameters: 3040 inStream inStream Input stream containing the message to 3041 generate MIC over. 3043 outStream outStream Output stream to write the GSS-API output 3044 token to. 3046 msgProp Instance of MessageProp that is used by the 3047 application to set the desired QOP. Set the desired 3048 QOP to 0 in msgProp to request the default QOP. 3049 Alternatively pass in "null" for msgProp to request 3050 default QOP. 3052 6.4.16. verifyMIC 3054 public void verifyMIC(byte []inTok, int tokOffset, int tokLen, 3055 byte[] inMsg, int msgOffset, int msgLen, 3056 MessageProp msgProp) throws GSSException 3058 Verifies the cryptographic MIC, contained in the token parameter, 3059 over the supplied message. This method is equivalent in 3060 functionality to its stream counterpart. 3062 The MessageProp object is instantiated by the application and is used 3063 by the underlying mechanism to return information to the caller such 3064 as the QOP indicating the strength of protection that was applied to 3065 the message and other supplementary message state information. 3067 Since some application-level protocols may wish to use tokens emitted 3068 by getMIC to provide "secure framing", implementations should support 3069 the calculation and verification of MICs over zero-length messages. 3071 Parameters: 3073 inTok Token generated by peer's getMIC method. 3075 GSS-API Java Bindings October 1999 3077 tokOffset The offset within the inTok where the token begins. 3079 tokLen The length of the token within the inTok (starting at 3080 the offset). 3082 inMsg Application message to verify the cryptographic MIC 3083 over. 3085 msgOffset The offset within the inMsg where the message begins. 3087 msgLen The length of the message within the inMsg (starting 3088 at the offset). 3090 msgProp Upon return from the method, this object will contain 3091 the applied QOP and supplementary information 3092 described in 4.12.3 stating whether the token was a 3093 duplicate, old, out of sequence or arriving after a 3094 gap. The confidentiality state will be set to 3095 "false". 3097 6.4.17. verifyMIC 3099 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3100 MessageProp msgProp) throws GSSException 3102 Verifies the cryptographic MIC, contained in the token parameter, 3103 over the supplied message. This method is equivalent in 3104 functionality to its byte array counterpart. 3106 The MessageProp object is instantiated by the application and is used 3107 by the underlying mechanism to return information to the caller such 3108 as the QOP indicating the strength of protection that was applied to 3109 the message and other supplementary message state information. 3111 Since some application-level protocols may wish to use tokens emitted 3112 by getMIC to provide "secure framing", implementations should support 3113 the calculation and verification of MICs over zero-length messages. 3115 Parameters: 3117 tokStream Input stream containing the token generated by peer's 3118 getMIC method. 3120 msgStream Input stream containing the application message to 3121 verify the cryptographic MIC over. 3123 msgProp Upon return from the method, this object will contain 3125 GSS-API Java Bindings October 1999 3127 the applied QOP and supplementary information 3128 described in 4.12.3 stating whether the token was a 3129 duplicate, old, out of sequence or arriving after a 3130 gap. The confidentiality state will be set to 3131 "false". 3133 6.4.18. export 3135 public byte [] export() throws GSSException 3137 Provided to support the sharing of work between multiple processes. 3138 This routine will typically be used by the context-acceptor, in an 3139 application where a single process receives incoming connection 3140 requests and accepts security contexts over them, then passes the 3141 established context to one or more other processes for message 3142 exchange. 3144 This method deactivates the security context and creates an 3145 interprocess token which, when passed to the byte array constructor 3146 of the GSSContext interface in another process, will re-activate the 3147 context in the second process. Only a single instantiation of a 3148 given context may be active at any one time; a subsequent attempt by 3149 a context exporter to access the exported security context will fail. 3151 The implementation may constrain the set of processes by which the 3152 interprocess token may be imported, either as a function of local 3153 security policy, or as a result of implementation decisions. For 3154 example, some implementations may constrain contexts to be passed 3155 only between processes that run under the same account, or which are 3156 part of the same process group. 3158 The interprocess token may contain security-sensitive information 3159 (for example cryptographic keys). While mechanisms are encouraged to 3160 either avoid placing such sensitive information within interprocess 3161 tokens, or to encrypt the token before returning it to the 3162 application, in a typical GSS-API implementation this may not be 3163 possible. Thus the application must take care to protect the 3164 interprocess token, and ensure that any process to which the token is 3165 transferred is trustworthy. 3167 6.4.19. requestMutualAuth 3169 public void requestMutualAuth(boolean state) throws GSSException 3171 Sets the request state of the mutual authentication flag for the 3172 context. This method is only valid before the context creation 3174 GSS-API Java Bindings October 1999 3176 process begins and only for the initiator. 3178 Parameters: 3180 state Boolean representing if mutual authentication should 3181 be requested during context establishment. 3183 6.4.20. requestReplayDet 3185 public void requestReplayDet(boolean state) throws GSSException 3187 Sets the request state of the replay detection service for the 3188 context. This method is only valid before the context creation 3189 process begins and only for the initiator. 3191 Parameters: 3193 state Boolean representing if replay detection is desired 3194 over the established context. 3196 6.4.21. requestSequenceDet 3198 public void requestSequenceDet(boolean state) throws GSSException 3200 Sets the request state for the sequence checking service of the 3201 context. This method is only valid before the context creation 3202 process begins and only for the initiator. 3204 Parameters: 3206 state Boolean representing if sequence detection is desired 3207 over the established context. 3209 6.4.22. requestCredDeleg 3211 public void requestCredDeleg(boolean state) throws GSSException 3213 Sets the request state for the credential delegation flag for the 3214 context. This method is only valid before the context creation 3215 process begins and only for the initiator. 3217 Parameters: 3219 state Boolean representing if credential delegation is 3220 desired. 3222 GSS-API Java Bindings October 1999 3224 6.4.23. requestAnonymity 3226 public void requestAnonymity(boolean state) throws GSSException 3228 Requests anonymous support over the context. This method is only 3229 valid before the context creation process begins and only for the 3230 initiator. 3232 Parameters: 3234 state Boolean representing if anonymity support is 3235 requested. 3237 6.4.24. requestConf 3239 public void requestConf(boolean state) throws GSSException 3241 Requests that confidentiality service be available over the context. 3242 This method is only valid before the context creation process begins 3243 and only for the initiator. 3245 Parameters: 3247 state Boolean indicating if confidentiality services are to 3248 be requested for the context. 3250 6.4.25. requestInteg 3252 public void requestInteg(boolean state) throws GSSException 3254 Requests that integrity services be available over the context. This 3255 method is only valid before the context creation process begins and 3256 only for the initiator. 3258 Parameters: 3260 state Boolean indicating if integrity services are to be 3261 requested for the context. 3263 6.4.26. requestLifetime 3265 public void requestLifetime(int lifetime) throws GSSException 3267 Sets the desired lifetime for the context in seconds. This method is 3268 only valid before the context creation process begins and only for 3270 GSS-API Java Bindings October 1999 3272 the initiator. 3274 Parameters: 3276 lifetime The desired context lifetime in seconds. 3278 6.4.27. setChannelBinding 3280 public void setChannelBinding(ChannelBinding cb) throws GSSException 3282 Sets the channel bindings to be used during context establishment. 3283 This method is only valid before the context creation process begins. 3285 Parameters: 3287 cb Channel bindings to be used. 3289 6.4.28. getCredDelegState 3291 public boolean getCredDelegState() 3293 Returns the state of the delegated credentials for the context. When 3294 issued before context establishment is completed or when the 3295 isProtReady method returns "false", it returns the desired state, 3296 otherwise it will indicate the actual state over the established 3297 context. 3299 6.4.29. getMutualAuthState 3301 public boolean getMutualAuthState() 3303 Returns the state of the mutual authentication option for the 3304 context. When issued before context establishment completes or when 3305 the isProtReady method returns "false", it returns the desired state, 3306 otherwise it will indicate the actual state over the established 3307 context. 3309 6.4.30. getReplayDetState 3311 public boolean getReplayDetState() 3313 Returns the state of the replay detection option for the context. 3314 When issued before context establishment completes or when the 3315 isProtReady method returns "false", it returns the desired state, 3317 GSS-API Java Bindings October 1999 3319 otherwise it will indicate the actual state over the established 3320 context. 3322 6.4.31. getSequenceDetState 3324 public boolean getSequenceDetState() 3326 Returns the state of the sequence detection option for the context. 3327 When issued before context establishment completes or when the 3328 isProtReady method returns "false", it returns the desired state, 3329 otherwise it will indicate the actual state over the established 3330 context. 3332 6.4.32. getAnonymityState 3334 public boolean getAnonymityState() 3336 Returns "true" if this is an anonymous context. When issued before 3337 context establishment completes or when the isProtReady method 3338 returns "false", it returns the desired state, otherwise it will 3339 indicate the actual state over the established context. 3341 6.4.33. isTransferable 3343 public boolean isTransferable() throws GSSException 3345 Returns "true" if the context is transferable to other processes 3346 through the use of the export method. This call is only valid on 3347 fully established contexts. 3349 6.4.34. isProtReady 3351 public boolean isProtReady() 3353 Returns "true" if the per message operations can be applied over the 3354 context. Some mechanisms may allow the usage of per-message 3355 operations before the context is fully established. This will also 3356 indicate that the get methods will return actual context state 3357 characteristics instead of the desired ones. 3359 6.4.35. getConfState 3361 public boolean getConfState() 3363 GSS-API Java Bindings October 1999 3365 Returns the confidentiality service state over the context. When 3366 issued before context establishment completes or when the isProtReady 3367 method returns "false", it returns the desired state, otherwise it 3368 will indicate the actual state over the established context. 3370 6.4.36. getIntegState 3372 public boolean getIntegState() 3374 Returns the integrity service state over the context. When issued 3375 before context establishment completes or when the isProtReady method 3376 returns "false", it returns the desired state, otherwise it will 3377 indicate the actual state over the established context. 3379 6.4.37. getLifetime 3381 public int getLifetime() 3383 Returns the context lifetime in seconds. When issued before context 3384 establishment completes or when the isProtReady method returns 3385 "false", it returns the desired lifetime, otherwise it will indicate 3386 the remaining lifetime for the context. 3388 6.4.38. getSrcName 3390 public GSSName getSrcName() throws GSSException 3392 Returns the name of the context initiator. This call is valid only 3393 after the context is fully established or the isProtReady method 3394 returns "true". It is guaranteed to return an MN. 3396 6.4.39. getTargName 3398 public GSSName getTargName() throws GSSException 3400 Returns the name of the context target (acceptor). This call is 3401 valid only after the context is fully established or the isProtReady 3402 method returns "true". It is guaranteed to return an MN. 3404 6.4.40. getMech 3406 public Oid getMech() throws GSSException 3408 GSS-API Java Bindings October 1999 3410 Returns the mechanism oid for this context. 3412 6.4.41. getDelegCred 3414 public GSSCredential getDelegCred() throws GSSException 3416 Returns the delegated credential object on the acceptor's side. To 3417 check for availability of delegated credentials call 3418 getDelegCredState. This call is only valid on fully established 3419 contexts. 3421 6.4.42. isInitiator 3423 public boolean isInitiator() throws GSSException 3425 Returns "true" if this is the initiator of the context. This call is 3426 only valid after the context creation process has started. 3428 6.5. public class MessageProp 3430 This is a utility class used within the per-message GSSContext 3431 methods to convey per-message properties. 3433 When used with the GSSContext interface's wrap and getMIC methods, an 3434 instance of this class is used to indicate the desired QOP and to 3435 request if confidentiality services are to be applied to caller 3436 supplied data (wrap only). To request default QOP, the value of 0 3437 should be used for QOP. 3439 When used with the unwrap and verifyMIC methods of the GSSContext 3440 interface, an instance of this class will be used to indicate the 3441 applied QOP and confidentiality services over the supplied message. 3442 In the case of verifyMIC, the confidentiality state will always be 3443 "false". Upon return from these methods, this object will also 3444 contain any supplementary status values applicable to the processed 3445 token. The supplementary status values can indicate old tokens, out 3446 of sequence tokens, gap tokens or duplicate tokens. 3448 6.5.1. Constructors 3450 public MessageProp(boolean privState) 3452 Constructor which sets QOP to 0 indicating that the default QOP is 3454 GSS-API Java Bindings October 1999 3456 requested. 3458 Parameters: 3460 privState The desired privacy state. "true" for privacy and 3461 "false" for integrity only. 3463 public MessageProp(int qop, boolean privState) 3465 Constructor which sets the values for the qop and privacy state. 3467 Parameters: 3469 qop The desired QOP. Use 0 to request a default QOP. 3471 privState The desired privacy state. "true" for privacy and 3472 "false" for integrity only. 3474 6.5.2. getQOP 3476 public int getQOP() 3478 Retrieves the QOP value. 3480 6.5.3. getPrivacy 3482 public boolean getPrivacy() 3484 Retrieves the privacy state. 3486 6.5.4. getMinorStatus 3488 public int getMinorStatus() 3490 Retrieves the minor status that the underlying mechanism might have 3491 set. 3493 6.5.5. getMinorString 3495 public String getMinorString() 3497 Returns a string explaining the mechanism specific error code. null 3498 will be returned when no mechanism error code has been set. 3500 GSS-API Java Bindings October 1999 3502 6.5.6. setQOP 3504 public void setQOP(int qopVal) 3506 Sets the QOP value. 3508 Parameters: 3510 qopVal The QOP value to be set. Use 0 to request a default 3511 QOP value. 3513 6.5.7. setPrivacy 3515 public void setPrivacy(boolean privState) 3517 Sets the privacy state. 3519 Parameters: 3521 privState The privacy state to set. 3523 6.5.8. isDuplicateToken 3525 public boolean isDuplicateToken() 3527 Returns "true" if this is a duplicate of an earlier token. 3529 6.5.9. isOldToken 3531 public boolean isOldToken() 3533 Returns "true" if the token's validity period has expired. 3535 6.5.10. isUnseqToken 3537 public boolean isUnseqToken() 3539 Returns "true" if a later token has already been processed. 3541 6.5.11. isGapToken 3543 public boolean isGapToken() 3545 GSS-API Java Bindings October 1999 3547 Returns "true" if an expected per-message token was not received. 3549 6.5.12. setSupplementaryStates 3551 public void setSupplementaryStates(boolean duplicate, 3552 boolean old, boolean unseq, boolean gap, 3553 int minorStatus, String minorString) 3555 This method sets the state for the supplementary information flags 3556 and the minor status in MessageProp. It is not used by the 3557 application but by the GSS implementation to return this information 3558 to the caller of a per-message context method. 3560 Parameters: 3562 duplicate true if the token was a duplicate of an earlier token, 3563 false otherwise 3565 old true if the token's validity period has expired, false 3566 otherwise 3568 unseq true if a later token has already been processed, 3569 false otherwise 3571 gap true if one or more predecessor tokens have not yet 3572 been successfully processed, false otherwise 3574 minorStatus the integer minor status code that the underlying 3575 mechanism wants to set 3577 minorString the textual representation of the minorStatus 3578 value 3580 6.6. public class ChannelBinding 3582 The GSS-API accommodates the concept of caller-provided channel 3583 binding information. Channel bindings are used to strengthen the 3584 quality with which peer entity authentication is provided during 3585 context establishment. They enable the GSS-API callers to bind the 3586 establishment of the security context to relevant characteristics 3587 like addresses or to application specific data. 3589 The caller initiating the security context must determine the 3590 appropriate channel binding values to set in the GSSContext object. 3592 GSS-API Java Bindings October 1999 3594 The acceptor must provide an identical binding in order to validate 3595 that received tokens possess correct channel-related characteristics. 3597 Use of channel bindings is optional in GSS-API. Since channel- 3598 binding information may be transmitted in context establishment 3599 tokens, applications should therefore not use confidential data as 3600 channel-binding components. 3602 6.6.1. Constructors 3604 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3605 byte[] appData) 3607 Create a ChannelBinding object with user supplied address information 3608 and data. "null" values can be used for any fields which the 3609 application does not want to specify. 3611 Parameters: 3613 initAddr The address of the context initiator. "null" value 3614 can be supplied to indicate that the application does 3615 not want to set this value. 3617 acceptAddrThe address of the context acceptor. "null" value can 3618 be supplied to indicate that the application does not 3619 want to set this value. 3621 appData Application supplied data to be used as part of the 3622 channel bindings. "null" value can be supplied to 3623 indicate that the application does not want to set 3624 this value. 3626 public ChannelBinding(byte[] appData) 3628 Creates a ChannelBinding object without any addressing information. 3630 Parameters: 3632 appData Application supplied data to be used as part of the 3633 channel bindings. 3635 6.6.2. getInitiatorAddress 3637 public InetAddress getInitiatorAddress() 3639 GSS-API Java Bindings October 1999 3641 Returns the initiator's address for this channel binding. "null" is 3642 returned if the address has not been set. 3644 6.6.3. getAcceptorAddress 3646 public InetAddress getAcceptorAddress() 3648 Returns the acceptor's address for this channel binding. "null" is 3649 returned if the address has not been set. 3651 6.6.4. getApplicationData 3653 public byte[] getApplicationData() 3655 Returns application data being used as part of the ChannelBinding. 3656 "null" is returned if no application data has been specified for the 3657 channel binding. 3659 6.6.5. equals 3661 public boolean equals(Object obj) 3663 Returns "true" if two channel bindings match. 3665 Parameters: 3667 obj Another channel binding to compare with. 3669 6.7. public class Oid 3671 This class represents Universal Object Identifiers (Oids) and their 3672 associated operations. 3674 Oids are hierarchically globally-interpretable identifiers used 3675 within the GSS-API framework to identify mechanisms and name formats. 3677 The structure and encoding of Oids is defined in ISOIEC-8824 and 3678 ISOIEC-8825. For example the Oid representation of Kerberos V5 3679 mechanism is "1.2.840.113554.1.2.2" 3681 The GSSName name class contains public static Oid objects 3683 GSS-API Java Bindings October 1999 3685 representing the standard name types defined in GSS-API. 3687 6.7.1. Constructors 3689 public Oid(String strOid) throws GSSException 3691 Creates an Oid object from a string representation of its integer 3692 components (e.g. "1.2.840.113554.1.2.2"). 3694 Parameters: 3696 strOid The string representation for the oid. 3698 public Oid(InputStream derOid) throws GSSException 3700 Creates an Oid object from its DER encoding. This refers to the full 3701 encoding including tag and length. The structure and encoding of 3702 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3703 identical in functionality to its byte array counterpart. 3705 Parameters: 3707 derOid Stream containing the DER encoded oid. 3709 public Oid(byte[] DEROid) throws GSSException 3711 Creates an Oid object from its DER encoding. This refers to the full 3712 encoding including tag and length. The structure and encoding of 3713 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3714 identical in functionality to its byte array counterpart. 3716 Parameters: 3718 derOid Byte array storing a DER encoded oid. 3720 6.7.2. toString 3722 public String toString() 3724 Returns a string representation of the oid's integer components in 3725 dot separated notation (e.g. "1.2.840.113554.1.2.2"). 3727 GSS-API Java Bindings October 1999 3729 6.7.3. equals 3731 public boolean equals(Object Obj) 3733 Returns "true" if the two Oid objects represent the same oid value. 3735 Parameters: 3737 obj Another Oid object to compare with. 3739 6.7.4. getDER 3741 public byte[] getDER() 3743 Returns the full ASN.1 DER encoding for this oid object, which 3744 includes the tag and length. 3746 6.7.5. containedIn 3748 public boolean containedIn(Oid[] oids) 3750 A utility method to test if an Oid object is contained within the 3751 supplied Oid object array. 3753 Parameters: 3755 oids An array of oids to search. 3757 6.8. public class GSSException extends Exception 3759 This exception is thrown whenever a fatal GSS-API error occurs 3760 including mechanism specific errors. It may contain both, the major 3761 and minor, GSS-API status codes. The mechanism implementers are 3762 responsible for setting appropriate minor status codes when throwing 3763 this exception. Aside from delivering the numeric error code(s) to 3764 the caller, this class performs the mapping from their numeric values 3765 to textual representations. All Java GSS-API methods are declared 3766 throwing this exception. 3768 All implementations are encouraged to use the Java 3769 internationalization techniques to provide local translations of the 3770 message strings. 3772 GSS-API Java Bindings October 1999 3774 6.8.1. Static Constants 3776 All valid major GSS-API error code values are declared as constants 3777 in this class. 3779 public static final int BAD_BINDINGS 3781 Channel bindings mismatch error. 3783 public static final int BAD_MECH 3785 Unsupported mechanism requested error. 3787 public static final int BAD_NAME 3789 Invalid name provided error. 3791 public static final int BAD_NAMETYPE 3793 Name of unsupported type provided error. 3795 public static final int BAD_STATUS 3797 Invalid status code error - this is the default status value. 3799 public static final int BAD_MIC 3801 Token had invalid integrity check error. 3803 public static final int CONTEXT_EXPIRED 3805 Specified security context expired error. 3807 public static final int CREDENTIALS_EXPIRED 3809 Expired credentials detected error. 3811 public static final int DEFECTIVE_CREDENTIAL 3813 GSS-API Java Bindings October 1999 3815 Defective credential error. 3817 public static final int DEFECTIVE_TOKEN 3819 Defective token error. 3821 public static final int FAILURE 3823 General failure, unspecified at GSS-API level. 3825 public static final int NO_CONTEXT 3827 Invalid security context error. 3829 public static final int NO_CRED 3831 Invalid credentials error. 3833 public static final int BAD_QOP 3835 Unsupported QOP value error. 3837 public static final int UNAUTHORIZED 3839 Operation unauthorized error. 3841 public static final int UNAVAILABLE 3843 Operation unavailable error. 3845 public static final int DUPLICATE_ELEMENT 3847 Duplicate credential element requested error. 3849 public static final int NAME_NOT_MN 3851 Name contains multi-mechanism elements error. 3853 GSS-API Java Bindings October 1999 3855 public static final int DUPLICATE_TOKEN 3857 The token was a duplicate of an earlier token. This is a fatal error 3858 code that may occur during context establishment. It is not used to 3859 indicate supplementary status values. The MessageProp object is used 3860 for that purpose. 3862 public static final int OLD_TOKEN 3864 The token's validity period has expired. This is a fatal error code 3865 that may occur during context establishment. It is not used to 3866 indicate supplementary status values. The MessageProp object is used 3867 for that purpose. 3869 public static final int UNSEQ_TOKEN 3871 A later token has already been processed. This is a fatal error code 3872 that may occur during context establishment. It is not used to 3873 indicate supplementary status values. The MessageProp object is used 3874 for that purpose. 3876 public static final int GAP_TOKEN 3878 An expected per-message token was not received. This is a fatal 3879 error code that may occur during context establishment. It is not 3880 used to indicate supplementary status values. The MessageProp object 3881 is used for that purpose. 3883 6.8.2. Constructors 3885 public GSSException(int majorCode) 3887 Creates a GSSException object with a specified major code. 3889 Parameters: 3891 majorCode The GSS error code causing this exception to be 3892 thrown. 3894 public GSSException(int majorCode, int minorCode, String minorString) 3896 Creates a GSSException object with the specified major code, minor 3897 code, and minor code textual explanation. This constructor is to be 3899 GSS-API Java Bindings October 1999 3901 used when the exception is originating from the security mechanism. 3902 It allows to specify the GSS code and the mechanism code. 3904 Parameters: 3906 majorCode The GSS error code causing this exception to be 3907 thrown. 3909 minorCode The mechanism error code causing this exception 3910 to be thrown. 3912 minorString The textual explanation of the mechanism error 3913 code. 3915 6.8.3. getMajor 3917 public int getMajor() 3919 Returns the major code representing the GSS error code that caused 3920 this exception to be thrown. 3922 6.8.4. getMinor 3924 public int getMinor() 3926 Returns the mechanism error code that caused this exception. The 3927 minor code is set by the underlying mechanism. Value of 0 indicates 3928 that mechanism error code is not set. 3930 6.8.5. getMajorString 3932 public String getMajorString() 3934 Returns a string explaining the GSS major error code causing this 3935 exception to be thrown. 3937 6.8.6. getMinorString 3939 public String getMinorString() 3941 Returns a string explaining the mechanism specific error code. null 3942 will be returned when no mechanism error code has been set. 3944 GSS-API Java Bindings October 1999 3946 6.8.7. setMinor 3948 public void setMinor(int minorCode, String message) 3950 Used internally by the GSS-API implementation and the underlying 3951 mechanisms to set the minor code and its textual representation. 3953 Parameters: 3955 minorCode The mechanism specific error code. 3957 message A textual explanation of the mechanism error code. 3959 6.8.8. toString 3961 public String toString() 3963 Returns a textual representation of both the major and minor status 3964 codes. 3966 6.8.9. getMessage 3968 public String getMessage() 3970 Returns a detailed message of this exception. Overrides 3971 Throwable.getMessage. It is customary in Java to use this method to 3972 obtain exception information. 3974 7. Sample Applications 3976 Full Copyright Statement 3978 Copyright (C) The Internet Society (1999). All Rights Reserved. 3980 This document and translations of it may be copied and furnished 3981 to others, and derivative works that comment on or otherwise explain 3982 it or assist in its implementation may be prepared, copied, published 3983 and distributed, in whole or in part, without restriction of any 3984 kind, provided that the above copyright notice and this paragraph are 3985 included on all such copies and derivative works. However, this 3986 document itself may not be modified in any way, such as by removing 3987 the copyright notice or references to the Internet Society or other 3988 Internet organizations, except as needed for the purpose of 3989 developing Internet standards in which case the procedures for 3991 GSS-API Java Bindings October 1999 3993 copyrights defined in the Internet Standards process must be 3994 followed, or as required to translate it into languages other than 3995 English. 3997 The limited permissions granted above are perpetual and will not 3998 be revoked by the Internet Society or its successors or assigns. 4000 This document and the information contained herein is provided on 4001 an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET 4002 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, 4003 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 4004 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4005 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4007 7.1. Simple GSS Context Initiator 4009 import org.ietf.jgss.*; 4011 /** 4012 * This is a partial sketch for a simple client program that acts 4013 * as a GSS context initiator. It illustrates how to use the Java 4014 * bindings for the GSS-API specified in 4015 * draft-ietf-cat-gssv2-javabind-03.txt. 4016 * 4017 * This code sketch assumes the existence of a GSS-API 4018 * implementation that supports the mechanism that it will need and 4019 * is present as a library package (org.ietf.jgss) either as part of 4020 * the standard JRE or in the CLASSPATH the application specifies. 4021 */ 4023 public class SimpleClient { 4025 private String serviceName; // name of peer (ie. server) 4026 private GSSCredential clientCred = null; 4027 private GSSContext context = null; 4028 private Oid mech; // underlying mechanism to use 4030 private GSSManager mgr = new GSSManager(); 4032 ... 4033 ... 4035 private void clientActions() { 4037 initializeGSS(); 4039 GSS-API Java Bindings October 1999 4041 establishContext(); 4042 doCommunication(); 4043 } 4045 /** 4046 * Acquire credentials for the client. 4047 */ 4048 private void initializeGSS() { 4050 try { 4052 clientCred = mgr.createCredential(null /*default princ*/, 4053 GSSCredential.INDEFINITE /* max lifetime */, 4054 mech /* mechanism to use */, 4055 GSSCredential.INITIATE_ONLY /* init context */); 4057 print("GSSCredential created for " + 4058 cred.getName().toString()); 4059 print("Credential lifetime (sec)=" + 4060 cred.getRemainingLifetime()); 4061 } catch (GSSException e) { 4062 print("GSS-API error in credential acquisition: " 4063 + e.getMessage()); 4064 ... 4065 ... 4066 } 4068 ... 4069 ... 4070 } 4072 /** 4073 * Does the security context establishment with the 4074 * server. 4075 */ 4076 private void establishContext() { 4078 byte[] inToken = new byte[0]; 4079 byte[] outToken = null; 4081 try { 4083 GSSName peer = mgr.createName(serviceName, 4084 GSSName.NT_HOSTBASED_SERVICE); 4086 context = mgr.createContext(peer, mech, gssCred, 4087 GSSContext.INDEFINITE/*lifetime*/); 4089 GSS-API Java Bindings October 1999 4091 // Will need to support confidentiality 4092 context.requestConf(true); 4094 while (!context.isEstablished()) { 4096 outToken = context.initSecContext(inToken, 0, 4097 inToken.length); 4099 if (outToken != null) 4100 writeGSSToken(outToken); 4102 if (!context.isEstablished()) 4103 inToken = readGSSToken(); 4104 } 4106 GSSName peer = context.getSrcName(); 4107 print("Security context established with " + peer + 4108 " using underlying mechanism " + mech.toString()); 4109 } catch (GSSException e) { 4110 print("GSS-API error during context establishment: " 4111 + e.getMessage()); 4112 ... 4113 ... 4114 } 4116 ... 4117 ... 4118 } 4120 /** 4121 * Sends some data to the server and reads back the 4122 * response. 4123 */ 4124 private void doCommunication() { 4125 byte[] inToken = null; 4126 byte[] outToken = null; 4127 byte[] buffer; 4129 // Container for multiple input-output arguments to and 4130 // from the per-message routines (e.g., wrap/unwrap). 4131 MessageProp messgInfo = new MessageProp(); 4133 try { 4135 /* 4136 * Now send some bytes to the server to be 4137 * processed. They will be integrity protected but 4138 * not encrypted for privacy. 4140 GSS-API Java Bindings October 1999 4142 */ 4144 buffer = readFromFile(); 4146 // Set privacy to false and use the default QOP 4147 messgInfo.setPrivacy(false); 4149 outToken = context.wrap(buffer, 0, buffer.length, 4150 messgInfo); 4152 writeGSSToken(outToken); 4154 /* 4155 * Now read the response from the server. 4156 */ 4158 inToken = readGSSToken(); 4159 buffer = context.unwrap(inToken, 0, inToken.length, 4160 messgInfo); 4161 // All ok if no exception was thrown! 4163 GSSName peer = context.getSrcName(); 4165 print("Message from " + peer.toString() 4166 + " arrived."); 4167 print("Was it encrypted? " + 4168 messgInfo.getPrivacy()); 4169 print("Duplicate Token? " + 4170 messgInfo.isDuplicateToken()); 4171 print("Old Token? " + 4172 messgInfo.isOldToken()); 4173 print("Unsequenced Token? " + 4174 messgInfo.isUnseqToken()); 4175 print("Gap Token? " + 4176 messgInfo.isGapToken()); 4178 ... 4179 ... 4181 } catch (GSSException e) { 4182 print("GSS-API error in per-message calls: " 4183 + e.getMessage()); 4184 ... 4185 ... 4186 } 4188 ... 4189 ... 4191 GSS-API Java Bindings October 1999 4193 } // end of doCommunication method 4195 ... 4196 ... 4198 } // end of class SimpleClient 4200 7.2. Simple GSS Context Acceptor 4202 import org.ietf.jgss.*; 4204 /** 4205 * This is a partial sketch for a simple server program that acts 4206 * as a GSS context acceptor. It illustrates how to use the Java 4207 * bindings for the GSS-API specified in 4208 * draft-ietf-cat-gssv2-javabind-03.txt. 4209 * 4210 * This code sketch assumes the existence of a GSS-API 4211 * implementation that supports the mechanisms that it will need and 4212 * is present as a library package (org.ietf.jgss) either as part of 4213 * the standard JRE or in the CLASSPATH the application specifies. 4214 */ 4216 import org.ietf.jgss.*; 4218 public class SimpleServer { 4220 private String serviceName; 4221 private GSSName name; 4222 private GSSCredential cred; 4224 private GSSManager mgr; 4226 ... 4227 ... 4229 /** 4230 * Wait for client connections, establish security contexts and 4231 * provide service. 4232 */ 4233 private void loop() { 4235 ... 4237 GSS-API Java Bindings October 1999 4239 ... 4241 mgr = new GSSManager(); 4243 name = mgr.createName(serviceName, 4244 GSSName.NT_HOSTBASED_SERVICE); 4246 cred = mgr.createCredential(name, 4247 GSSCredential.INDEFINITE, 4248 null, 4249 GSSCredential.ACCEPT_ONLY); 4251 // Loop infinitely 4252 while (true) { 4254 Socket s = serverSock.acceptSecContext(); 4256 // Start a new thread to serve this connection 4257 Thread serverThread = new ServerThread(s); 4258 serverThread.start(); 4260 } 4261 } 4263 /** 4264 * Inner class ServerThread whose run() method provides the 4265 * secure service to a connection. 4266 */ 4268 private class ServerThread extends Thread { 4270 ... 4271 ... 4273 /** 4274 * Deals with the connection from one client. It also 4275 * handles all GSSException's thrown while talking to 4276 * this client. 4277 */ 4278 public void run() { 4280 byte[] inToken = null; 4281 byte[] outToken = null; 4282 byte[] buffer; 4284 GSSName peer; 4286 GSS-API Java Bindings October 1999 4288 // Container for multiple input-output arguments to and 4289 // from the per-message routines (ie. wrap/unwrap). 4290 MessageProp supplInfo = new MessageProp(); 4292 GSSContext secContext = null; 4294 try { 4296 // Now do the context establishment loop 4298 GSSContext context = mgr.createContext(cred); 4300 while (!context.isEstablished()) { 4302 inToken = readGSSToken(); 4304 outToken = context.acceptSecContext(inToken, 0, 4305 inToken.length); 4307 if (outToken != null) 4308 writeGSSToken(outToken); 4310 } 4312 // SimpleServer wants confidentiality to be 4313 // available. Check for it. 4314 if (!context.getConfState()){ 4315 ... 4316 ... 4317 } 4319 GSSName peer = context.getSrcName(); 4320 Oid mech = context.getMech(); 4321 print("Security context established with " + 4322 peer.toString() + 4323 " using underlying mechanism " + 4324 mech.toString() + 4325 " from Provider " + 4326 context.getProvider().getName()); 4328 // Now read the bytes sent by the client to be 4329 // processed. 4330 inToken = readGSSToken(); 4332 // Unwrap the message 4334 GSS-API Java Bindings October 1999 4336 buffer = context.unwrap(inToken, 0, inToken.length, 4337 supplInfo); 4338 // All ok if no exception was thrown! 4340 // Print other supplementary per-message status 4341 // information 4343 print("Message from " + 4344 peer.toString() + " arrived."); 4345 print("Was it encrypted? " + 4346 supplInfo.getPrivacy()); 4347 print("Duplicate Token? " + 4348 supplInfo.isDuplicateToken()); 4349 print("Old Token? " + supplInfo.isOldToken()); 4350 print("Unsequenced Token? " + 4351 supplInfo.isUnseqToken()); 4352 print("Gap Token? " + supplInfo.isGapToken()); 4354 /* 4355 * Now process the bytes and send back an encrypted 4356 * response. 4357 */ 4359 buffer = serverProcess(buffer); 4361 // Encipher it and send it across 4363 supplInfo.setPrivacy(true); // privacy requested 4364 supplInfo.setQOP(0); // default QOP 4365 outToken = context.wrap(buffer, 0, buffer.length, 4366 supplInfo); 4367 writeGSSToken(outToken); 4369 } catch (GSSException e) { 4370 print("GSS-API Error: " + e.getMessage()); 4371 // Alternatively, could call e.getMajorMessage() 4372 // and e.getMinorMessage() 4373 print("Abandoning security context."); 4375 ... 4376 ... 4378 } 4380 ... 4381 ... 4383 } // end of run method in ServerThread 4385 GSS-API Java Bindings October 1999 4387 } // end of inner class ServerThread 4389 ... 4390 ... 4392 } // end of class SimpleServer 4394 8. Acknowledgments 4396 This proposed API leverages earlier work performed by the IETF's CAT 4397 WG as outlined in both RFC 2078 and J. Wray's C-bindings draft for 4398 the GSS-API. Many conceptual definitions, implementation directions, 4399 and explanations have been included from the C-bindings draft. 4401 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4402 Saltz and other members of Sun's development team for their helpful 4403 input, comments and suggestions. 4405 We would also like to thank Joe Salowey, and Michael Smith for many 4406 insightful ideas and suggestions that have contributed to this draft. 4408 GSS-API Java Bindings October 1999 4410 9. Bibliography 4412 [GSSAPIv2] 4413 J. Linn, "Generic Security Service Application Program Interface, 4414 Version 2", RFC 2078, January 1997. 4416 [GSSAPIv2-UPDATE] 4417 J. Linn, "Generic Security Service Application Program Interface, 4418 Version 2, Update 1", IETF work in progress, Internet Draft, July 4419 1998. 4421 [GSSAPI-Cbind] 4422 J. Wray, "Generic Security Service API Version 2 : C-bindings", IETF 4423 work in progress, Internet Draft, July 1998. 4425 [KERBEROS_V5] 4426 J. Linn, "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, June 4427 1996. 4429 [SPKM] 4430 C. Adams, "The Simple Public-Key GSS-API Mechanism", RFC 2025, 4431 October 1996. 4433 GSS-API Java Bindings October 1999 4435 10. Author's Address 4437 Address comments related to this memorandum to: 4439 4441 Jack Kabat 4442 ValiCert, Inc. 4443 1215 Terra Bella Avenue 4444 Mountain View, CA 4445 94043, USA 4447 Phone: +1-650-567-5496 4448 E-mail: jackk@valicert.com 4450 Mayank Upadhyay 4451 Sun Microsystems, Inc. 4452 901 San Antonio Road, MS CUP02-102 4453 Palo Alto, CA 94303 4455 Phone: +1-408-517-5956 4456 E-mail: mdu@eng.sun.com