idnits 2.17.1 draft-ietf-cat-gssv2-javabind-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-27) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** 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? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard 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. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 258 has weird spacing: '...ment of a sec...' == Line 1062 has weird spacing: '...ith the major...' == Line 1130 has weird spacing: '...rmation to en...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 1998) is 9387 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 3591 looks like a reference -- Missing reference section? 'SPKM' on line 3608 looks like a reference -- Missing reference section? 'KERBV5' on line 42 looks like a reference -- Missing reference section? 'GSSAPI-C' on line 221 looks like a reference -- Missing reference section? '0' on line 2200 looks like a reference -- Missing reference section? 'GSSAPIv2-UPDATE' on line 3595 looks like a reference -- Missing reference section? 'GSSAPI-Cbind' on line 3600 looks like a reference Summary: 9 errors (**), 0 flaws (~~), 4 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet-Draft Jack Kabat 3 IETF Common Authentication Technology WG Sun Microsystems 4 Document: August 1998 6 Generic Security Service API Version 2 : Java bindings 8 Status of this Memo 10 This document is an Internet-Draft. Internet-Drafts are working 11 documents of the Internet Engineering Task Force (IETF), its areas, 12 and its working groups. Note that other groups may also distribute 13 working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six months 16 and may be updated, replaced, or obsoleted by other documents at any 17 time. It is inappropriate to use Internet- Drafts as reference 18 material or to cite them other than as "work in progress." 20 To view the entire list of current Internet-Drafts, please check the 21 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 22 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern 23 Europe), ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific 24 Rim), ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 26 Comments on this draft should be sent to "cat-ietf@mit.edu", the IETF 27 Common Authentication Technology WG discussion list. 29 Abstract 31 The Generic Security Services Application Program Interface (GSS-API) 32 offers application programmers uniform access to security services 33 atop a variety of underlying cryptographic mechanisms. This document 34 specifies the Java bindings for GSS-API which is described at a 35 language independent conceptual level in RFC 2078 [GSSAPIv2]. 37 The GSS-API allows a caller application to authenticate a principal 38 identity, to delegate rights to a peer, and to apply security 39 services such as confidentiality and integrity on a per-message 40 basis. Examples of security mechanisms defined for GSS-API are The 41 Simple Public-Key GSS-API Mechanism [SPKM] and The Kerberos Version 5 42 GSS-API Mechanism [KERBV5]. 44 GSS-API Java Bindings August 1998 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 49 2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 6 50 3. GSS-API Classes . . . . . . . . . . . . . . . . . . . . . . 8 51 3.1. GSSCredential class . . . . . . . . . . . . . . . . . . . 8 52 3.2. GSSContext class . . . . . . . . . . . . . . . . . . . . . 9 53 3.3. GSSName class . . . . . . . . . . . . . . . . . . . . . 10 54 3.4. GSSManager class . . . . . . . . . . . . . . . . . . . . 11 55 3.5. GSSException class . . . . . . . . . . . . . . . . . . . 11 56 3.6. Oid class . . . . . . . . . . . . . . . . . . . . . . . 11 57 3.7. MessageProp class . . . . . . . . . . . . . . . . . . . 12 58 3.8. ChannelBinding class . . . . . . . . . . . . . . . . . . 12 59 4. Calling Conventions . . . . . . . . . . . . . . . . . . . 12 60 4.1. Integer types . . . . . . . . . . . . . . . . . . . . . 12 61 4.2. Opaque Data types . . . . . . . . . . . . . . . . . . . 13 62 4.3. Strings . . . . . . . . . . . . . . . . . . . . . . . . 13 63 4.4. Object Identifiers . . . . . . . . . . . . . . . . . . . 13 64 4.5. Object Identifier Sets . . . . . . . . . . . . . . . . . 13 65 4.6. Credentials . . . . . . . . . . . . . . . . . . . . . . 14 66 4.7. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 16 67 4.8. Authentication tokens . . . . . . . . . . . . . . . . . 16 68 4.9. Interprocess tokens . . . . . . . . . . . . . . . . . . 16 69 4.10. Error Reporting . . . . . . . . . . . . . . . . . . . . 17 70 4.10.1. GSS status codes . . . . . . . . . . . . . . . . . . 17 71 4.10.2. Mechanism-specific status codes . . . . . . . . . . . 19 72 4.10.3. Supplementary status codes . . . . . . . . . . . . . 20 73 4.11. Names . . . . . . . . . . . . . . . . . . . . . . . . . 20 74 4.12. Channel Bindings . . . . . . . . . . . . . . . . . . . 23 75 4.13. Stream Objects . . . . . . . . . . . . . . . . . . . . 24 76 4.14. Optional Parameters . . . . . . . . . . . . . . . . . . 24 77 5. Additional Controls . . . . . . . . . . . . . . . . . . . 24 78 5.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . 26 79 5.2. Mutual Authentication . . . . . . . . . . . . . . . . . 26 80 5.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 27 81 5.4. Anonymous Authentication . . . . . . . . . . . . . . . . 28 82 5.5. Confidentiality . . . . . . . . . . . . . . . . . . . . 29 83 5.6. Inter-process Context Transfer . . . . . . . . . . . . . 29 84 5.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 30 85 6. Detailed GSS-API Class Description . . . . . . . . . . . . 30 86 6.1. public class GSSName . . . . . . . . . . . . . . . . . . 30 87 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . . 30 88 6.1.2. Class Constants . . . . . . . . . . . . . . . . . . . 31 89 6.1.3. Constructors . . . . . . . . . . . . . . . . . . . . . 32 90 6.1.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 34 91 6.1.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 34 92 6.1.6. canonicalize . . . . . . . . . . . . . . . . . . . . . 34 93 6.1.7. export . . . . . . . . . . . . . . . . . . . . . . . . 35 94 GSS-API Java Bindings August 1998 96 6.1.8. toString . . . . . . . . . . . . . . . . . . . . . . . 35 97 6.1.9. getStringNameType . . . . . . . . . . . . . . . . . . 35 98 6.1.10. clone . . . . . . . . . . . . . . . . . . . . . . . . 35 99 6.1.11. isAnonymous . . . . . . . . . . . . . . . . . . . . . 35 100 6.2. public class GSSCredential . . . . . . . . . . . . . . . 35 101 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . . 36 102 6.2.2. Class Constants . . . . . . . . . . . . . . . . . . . 37 103 6.2.3. Constructors . . . . . . . . . . . . . . . . . . . . . 37 104 6.2.4. dispose . . . . . . . . . . . . . . . . . . . . . . . 39 105 6.2.5. getGSSName . . . . . . . . . . . . . . . . . . . . . . 39 106 6.2.6. getGSSName . . . . . . . . . . . . . . . . . . . . . . 40 107 6.2.7. getRemainingLifetime . . . . . . . . . . . . . . . . . 40 108 6.2.8. getRemainingInitLifetime . . . . . . . . . . . . . . . 40 109 6.2.9. getRemainingAcceptLifetime . . . . . . . . . . . . . . 40 110 6.2.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 41 111 6.2.11. getUsage . . . . . . . . . . . . . . . . . . . . . . 41 112 6.2.12. getMechs . . . . . . . . . . . . . . . . . . . . . . 41 113 6.2.13. add . . . . . . . . . . . . . . . . . . . . . . . . . 41 114 6.2.14. equals . . . . . . . . . . . . . . . . . . . . . . . 42 115 6.3. public class GSSContext . . . . . . . . . . . . . . . . 43 116 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . . 44 117 6.3.2. Class Constants . . . . . . . . . . . . . . . . . . . 45 118 6.3.3. Constructors . . . . . . . . . . . . . . . . . . . . . 46 119 6.3.4. init . . . . . . . . . . . . . . . . . . . . . . . . . 47 120 6.3.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 47 121 6.3.5. init . . . . . . . . . . . . . . . . . . . . . . . . . 48 122 6.3.5.1. Example Code . . . . . . . . . . . . . . . . . . . . 49 123 6.3.6. accept . . . . . . . . . . . . . . . . . . . . . . . . 50 124 6.3.6.1. Example Code . . . . . . . . . . . . . . . . . . . . 50 125 6.3.7. accept . . . . . . . . . . . . . . . . . . . . . . . . 51 126 6.3.7.1. Example Code . . . . . . . . . . . . . . . . . . . . 52 127 6.3.8. isEstablished . . . . . . . . . . . . . . . . . . . . 52 128 6.3.9. dispose . . . . . . . . . . . . . . . . . . . . . . . 52 129 6.3.10. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 53 130 6.3.11. wrap . . . . . . . . . . . . . . . . . . . . . . . . 53 131 6.3.12. wrap . . . . . . . . . . . . . . . . . . . . . . . . 54 132 6.3.13. unwrap . . . . . . . . . . . . . . . . . . . . . . . 55 133 6.3.14. unwrap . . . . . . . . . . . . . . . . . . . . . . . 56 134 6.3.15. getMIC . . . . . . . . . . . . . . . . . . . . . . . 56 135 6.3.16. getMIC . . . . . . . . . . . . . . . . . . . . . . . 57 136 6.3.17. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 57 137 6.3.18. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 58 138 6.3.19. export . . . . . . . . . . . . . . . . . . . . . . . 59 139 6.3.20. requestMutualAuth . . . . . . . . . . . . . . . . . . 60 140 6.3.21. requestReplayDet . . . . . . . . . . . . . . . . . . 60 141 6.3.22. requestSequenceDet . . . . . . . . . . . . . . . . . 60 142 6.3.23. requestCredDeleg . . . . . . . . . . . . . . . . . . 60 143 6.3.24. requestAnonymity . . . . . . . . . . . . . . . . . . 61 144 GSS-API Java Bindings August 1998 146 6.3.25. requestConf . . . . . . . . . . . . . . . . . . . . . 61 147 6.3.26. requestInteg . . . . . . . . . . . . . . . . . . . . 61 148 6.3.27. requestLifetime . . . . . . . . . . . . . . . . . . . 62 149 6.3.28. setChannelBinding . . . . . . . . . . . . . . . . . . 62 150 6.3.29. getCredDelegState . . . . . . . . . . . . . . . . . . 62 151 6.3.30. getMutualAuthState . . . . . . . . . . . . . . . . . 62 152 6.3.31. getReplayDetState . . . . . . . . . . . . . . . . . . 63 153 6.3.32. getSequenceDetState . . . . . . . . . . . . . . . . . 63 154 6.3.33. getAnonymityState . . . . . . . . . . . . . . . . . . 63 155 6.3.34. isTransferable . . . . . . . . . . . . . . . . . . . 63 156 6.3.35. isProtReady . . . . . . . . . . . . . . . . . . . . . 63 157 6.3.36. getConfState . . . . . . . . . . . . . . . . . . . . 64 158 6.3.37. getIntegState . . . . . . . . . . . . . . . . . . . . 64 159 6.3.38. getLifetime . . . . . . . . . . . . . . . . . . . . . 64 160 6.3.39. getSrcName . . . . . . . . . . . . . . . . . . . . . 64 161 6.3.40. getTargName . . . . . . . . . . . . . . . . . . . . . 64 162 6.3.41. getMech . . . . . . . . . . . . . . . . . . . . . . . 65 163 6.3.42. getDelegCred . . . . . . . . . . . . . . . . . . . . 65 164 6.3.43. isInitiator . . . . . . . . . . . . . . . . . . . . . 65 165 6.4. public class MessageProp . . . . . . . . . . . . . . . . 65 166 6.4.1. Constructors . . . . . . . . . . . . . . . . . . . . . 66 167 6.4.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . . 66 168 6.4.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . . 66 169 6.4.4. setQOP . . . . . . . . . . . . . . . . . . . . . . . . 66 170 6.4.5. setPrivacy . . . . . . . . . . . . . . . . . . . . . . 67 171 6.4.6. isDuplicateToken . . . . . . . . . . . . . . . . . . . 67 172 6.4.7. isOldToken . . . . . . . . . . . . . . . . . . . . . . 67 173 6.4.8. isUnseqToken . . . . . . . . . . . . . . . . . . . . . 67 174 6.4.9. isGapToken . . . . . . . . . . . . . . . . . . . . . . 67 175 6.5. public class GSSManager . . . . . . . . . . . . . . . . 67 176 6.5.1. getMechs . . . . . . . . . . . . . . . . . . . . . . . 68 177 6.5.2. getNamesForMech . . . . . . . . . . . . . . . . . . . 68 178 6.5.3. getMechsForName . . . . . . . . . . . . . . . . . . . 68 179 6.5.4. getDefaultMech . . . . . . . . . . . . . . . . . . . . 68 180 6.6. public class ChannelBinding . . . . . . . . . . . . . . 68 181 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . . 69 182 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 70 183 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . . 70 184 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . . 70 185 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . . 70 186 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 70 187 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . . 71 188 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . . 71 189 6.7.3. toRFC2078String . . . . . . . . . . . . . . . . . . . 72 190 6.7.4. equals . . . . . . . . . . . . . . . . . . . . . . . . 72 191 6.7.5. getDER . . . . . . . . . . . . . . . . . . . . . . . . 72 192 6.7.6. containedIn . . . . . . . . . . . . . . . . . . . . . 72 193 6.8. public class GSSException extends Exception . . . . . . 72 194 GSS-API Java Bindings August 1998 196 6.8.1. Class Constants . . . . . . . . . . . . . . . . . . . 73 197 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . . 75 198 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . . 76 199 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . . 76 200 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . . 76 201 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . . 77 202 6.8.7. setMinor . . . . . . . . . . . . . . . . . . . . . . . 77 203 6.8.8. toString . . . . . . . . . . . . . . . . . . . . . . . 77 204 6.8.9. getMessage . . . . . . . . . . . . . . . . . . . . . . 77 205 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . 77 206 8. Bibliography . . . . . . . . . . . . . . . . . . . . . . . 79 207 9. Author's Address . . . . . . . . . . . . . . . . . . . . . 80 208 GSS-API Java Bindings August 1998 210 1. Introduction 212 This document specifies Java language bindings for the Generic 213 Security Services Application Programming Interface (GSS-API) Version 214 2. GSS-API Version 2 is described in a language independent format in 215 RFC 2078 [GSSAPIv2]. The GSS-API allows a caller application to 216 authenticate a principal identity, to delegate rights to a peer, and 217 to apply security services such as confidentiality and integrity on a 218 per-message basis. 220 This document leverages on the work performed by the WG in the area 221 of RFC 2078 [GSSAPIv2] the C-bindings draft [GSSAPI-C]. Whenever 222 appropriate, text has been used from the C-bindings document to 223 explain generic concepts and provide direction to the implementors. 225 The design goals of this API have been to satisfy all the 226 functionality defined in RFC 2078 and to provide these services in an 227 object oriented method. Further, the specification presents an API 228 that will naturally fit within the operation environment of the Java 229 platform. Readers are assumed to be familiar with both the GSS-API 230 and the Java platform. 232 2. GSS-API Operational Paradigm 234 The Generic Security Service Application Programming Interface 235 [GSSAPIv2] defines a generic security API to calling applications. 236 It allows a communicating application to authenticate the user 237 associated with another application, to delegate rights to another 238 application, and to apply security services such as confidentiality 239 and integrity on a per-message basis. 241 There are four stages to using GSS-API: 243 1) The application acquires a set of credentials with which it 244 may prove its identity to other processes. The 245 application's credentials vouch for its global identity, 246 which may or may not be related to any local username under 247 which it may be running. 249 2) A pair of communicating applications establish a joint 250 security context using their credentials. The security 251 context encapsulates shared state information, which is 252 required in order that per-message security services may be 253 provided. Examples of state information that might be 254 GSS-API Java Bindings August 1998 256 shared between applications as part of a security context 257 are cryptographic keys, and message sequence numbers. As 258 part of the establishment of a security context, the 259 context initiator is authenticated to the responder, and 260 may require that the responder is authenticated back to the 261 initiator. The initiator may optionally give the responder 262 the right to initiate further security contexts, acting as 263 an agent or delegate of the initiator. This transfer of 264 rights is termed "delegation", and is achieved by creating 265 a set of credentials, similar to those used by the 266 initiating application, but which may be used by the 267 responder. 269 A GSSContext object is used to establish and maintain the 270 shared information that makes up the security context. 271 Certain GSSContext methods will generate a token, which 272 applications treat as cryptographically protected, opaque 273 data. The caller of such GSSContext method is responsible 274 for transferring the token to the peer application, 275 encapsulated if necessary in an application-to-application 276 protocol. On receipt of such a token, the peer application 277 should pass it to a corresponding GSSContext method which 278 will decode the token and extract the information, updating 279 the security context state information accordingly. 281 3) Per-message services are invoked on a GSSContext object to 282 apply either: 284 integrity and data origin authentication, or 286 confidentiality, integrity and data origin 287 authentication 289 to application data, which are treated by GSS-API as 290 arbitrary octet-strings. An application transmitting a 291 message that it wishes to protect will call the appropriate 292 GSSContext method (getMIC or wrap) to apply protection, and 293 send the resulting token to the receiving application. The 294 receiver will pass the received token (and, in the case of 295 data protected by getMIC, the accompanying message-data) to 296 the corresponding decoding method of the GSSContext class 297 (verifyMIC or unwrap) to remove the protection and validate 298 the data. 300 4) At the completion of a communications session (which may 301 extend across several transport connections), each 302 application uses a GSSContext method to invalidate the 303 security context and release any system or cryptographic 304 GSS-API Java Bindings August 1998 306 resources held. Multiple contexts may also be used (either 307 successively or simultaneously) within a single 308 communications association, at the discretion of the 309 applications. 311 3. GSS-API Classes 313 This section presents a brief description of the classes comprising 314 the GSS-API class library and the corresponding RFC 2078 315 functionality implemented by each of them. Detailed description of 316 all the classes and their corresponding methods is presented in 317 section 6. 319 3.1. GSSCredential class 321 The GSSCredential class is responsible for the encapsulation of GSS- 322 API credentials. Credentials identify a single entity and provide the 323 necessary cryptographic information to enable the creation of a 324 context on behalf of that entity. A single GSSCredential may contain 325 multiple mechanism specific credentials, each referred to as a 326 credential element. The GSSCredential class implements the 327 functionality of the following GSS-API routines: 329 RFC 2078 Routine Function Section(s) 331 gss_acquire_cred Acquire credential for use. 6.2.3 333 gss_add_cred Constructs credentials 6.2.13 334 incrementally. 336 gss_inquire_cred Obtain information about 6.2.5-6.2.12 337 credential. 339 gss_inquire_cred_by_mech Obtain per-mechanism 6.2.5-6.2.12 340 information about 341 a credential. 343 gss_release_cred Disposes of credentials 6.2.4 344 after use. 346 GSS-API Java Bindings August 1998 348 3.2. GSSContext class 350 This class encapsulates the functionality of context-level calls 351 required for security context establishment and management between 352 peers as well as the per-message services offered to applications. A 353 context is established between a pair of peers and allows the usage 354 of security services on a per-message basis on application data. It 355 is created over a single security mechanism. The GSSContext class 356 implements the functionality of the following GSS-API routines: 358 RFC 2078 Routine Function Section(s) 360 gss_init_sec_context Initiate the creation of a 6.3.4, 361 security context with 6.3.5 362 a peer. 364 gss_accept_sec_context Accept a security context 6.3.6, 365 initiated by a peer. 6.3.7 367 gss_delete_sec_context Destroy a security context. 6.3.9 369 gss_context_time Obtain remaining context 6.3.38 370 time. 372 gss_inquire_context Obtain context 6.3.38 to 373 characteristics. 6.3.43 375 gss_wrap_size_limit Determine token-size limit 6.3.10 376 for gss_wrap. 378 gss_export_sec_context Transfer security context 6.3.19 379 to another process. 381 gss_import_sec_context Create a previously exported 6.3.3 382 context. 384 gss_get_mic Calculate a cryptographic 6.3.15, 385 Message Integrity Code (MIC) 6.3.16 386 for a message. 388 gss_verify_mic Verify integrity on a received 6.3.17, 389 message. 6.3.18 391 gss_wrap Attach a MIC to a message and 6.3.11, 392 optionally encrypt the message 6.3.12 393 content. 395 GSS-API Java Bindings August 1998 397 gss_unwrap Obtain a previously wrapped 6.3.13, 398 application message verifying 6.3.14 399 its integrity and optionally 400 decrypting it. 402 The functionality offered by the gss_process_context_token routine 403 has not been included in the Java bindings specification. The 404 corresponding functionality of gss_delete_sec_context has also been 405 modified to not return any peer tokens. This has been proposed in 406 accordance to the recommendations stated in the RFC 2078 update 407 draft. GSSContext does offer the functionality of destroying the 408 locally-stored context information. 410 3.3. GSSName class 412 GSS-API names are represented in the Java bindings through the 413 GSSName class. Different name formats and their definitions are 414 identified with universal Object Identifiers (oids). The format of 415 the names can be derived based on the unique oid of each name type. 416 The following GSS-API routines are implemented by the GSSName object: 418 RFC 2078 Routine Function Section(s) 420 gss_import_name Create an internal name from 6.1.3 421 the supplied information. 423 gss_display_name Covert internal name 6.1.8, 6.1.9 424 representation to text format. 426 gss_compare_name Compare two internal names. 6.1.4, 6.1.5 428 gss_release_name Release resources associated N/A 429 with the internal name. 431 gss_canonicalize_name Convert an internal name to a 6.1.3, 6.1.6 432 mechanism name. 434 gss_export_name Convert a Mechanism name to 6.1.7 435 export format. 437 gss_duplicate_name Create a copy of the internal 6.1.10 438 name. 440 GSS-API Java Bindings August 1998 442 3.4. GSSManager class 444 The responsibilities of the GSSManager class is to provide 445 functionality common to the entire GSS-API class library. This would 446 include queries about the mechanisms supported and the default 447 mechanism value. GSSManager implements the following RFC 2078 448 routines: 450 RFC 2078 Routine Function Section 452 gss_inquire_names_for_mech List the name types 6.5.2 453 supported by the 454 specified mechanism. 456 gss_inquire_mechs_for_name List the mechanisms 6.5.3 457 supporting the 458 specified name type. 460 gss_indicate_mechs List the mechanisms 6.5.1 461 supported by this GSS-API 462 implementation. 464 3.5. GSSException class 466 Exceptions are used in the Java bindings to signal fatal errors to 467 the calling applications. This replaces the major and minor codes 468 used in the C-bindings specification as a method of signaling 469 failures. The GSSException class handles both minor and major codes, 470 as well as their translation into textual representation. All GSS- 471 API methods are declared as possibly throwing this exception. 473 RFC 2078 Routine Function Section 475 gss_display_status Retrieve textual 6.8.5, 6.8.6, 476 representation of error 6.8.8, 6.8.9 477 codes. 479 3.6. Oid class 481 This utility class is used to represent Universal Object Identifiers 482 and their associated operations. GSS-API uses object identifiers to 483 distinguish between security mechanisms and name types. This class, 484 aside from being used whenever an object identifier is needed, 485 implements the following GSS-API functionality: 487 GSS-API Java Bindings August 1998 489 RFC 2078 Routine Function Section 491 gss_test_oid_set_member Determine if the specified oid 6.7.6 492 is part of a set of oids. 494 3.7. MessageProp class 496 This helper class is used in the per-message operations of the 497 GSSContext class to convey the requested and applied per-message 498 options. An instance of this class is used to specify the desired QOP 499 and confidentiality state for a per-message operation of the 500 GSSContext class. Upon return from those methods, this object will 501 contain the applied QOP and confidentiality state as well as any 502 supplementary status information for the completed per-message 503 operation. 505 3.8. ChannelBinding class 507 An instance of this class is used to specify channel binding 508 information to the GSSContext object before the start of a security 509 context establishment. The application may use a byte array to 510 specify application data to be used in the channel binding as well as 511 using instances of the InetAddress. InetAddress is currently the only 512 address type defined within the Java platform and as such, it is the 513 only one supported within the ChannelBinding class. 515 4. Calling Conventions 517 Java provides the implementors with more than just a syntax for the 518 language, but also an operational environment. For example, memory is 519 automatically managed and does not require application intervention. 520 These language features have allowed for a simpler API and have led 521 to the elimination of certain GSS-API functions. 523 4.1. Integer types 525 All numeric values are declared as "int" primitive Java type. The 526 Java specification guarantees that this will be a 32 bit two's 527 complement signed number. 529 Throughout this API, the "boolean" primitive Java type is used 530 wherever a boolean value is required or returned. 532 GSS-API Java Bindings August 1998 534 4.2. Opaque Data types 536 Java byte arrays are used to represent opaque data types which are 537 consumed and produced by the GSS-API in the forms of tokens. Java 538 arrays contain a length field which enables the users to easily 539 determine their size. The language has automatic garbage collection 540 which alleviates the need by developers to release memory and 541 simplifies buffer ownership issues. 543 4.3. Strings 545 The String object will be used to represent all textual data. The 546 Java String object, transparently treats all characters as two-byte 547 Unicode characters which allows support for many locals. All routines 548 returning or accepting textual data will use the String object. 550 4.4. Object Identifiers 552 An Oid object will be used to represent Universal Object Identifiers 553 (Oids). Oids are ISO-defined, hierarchically globally-interpretable 554 identifiers used within the GSS-API framework to identify security 555 mechanisms and name formats. The Oid object can be created from a 556 string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as 557 well as from its ASN.1 DER encoding. Methods are also provided to 558 test equality and provide the DER representation for the object. 560 An important feature of the Oid class is that its instances are 561 immutable - i.e. there are no methods defined that allow one to 562 change the contents of an Oid. This property allows one to treat 563 these objects as "statics" without the need to perform copies. 565 Certain routines allow the usage of a default oid. A "null" value can 566 be used in those cases. 568 4.5. Object Identifier Sets 570 The Java bindings represents object identifiers sets as arrays of Oid 571 objects. All Java arrays contain a length field which allows for easy 572 manipulation and reference. 574 In order to support the full functionality of RFC 2078, the Oid class 575 includes a method which checks for existence of an Oid object within 576 a specified array. This is equivalent in functionality to 577 gss_test_oid_set_member. The use of Java arrays and Java's automatic 578 garbage collection has eliminated the need for the following 579 GSS-API Java Bindings August 1998 581 routines: gss_create_empty_oid_set, gss_release_oid_set, and 582 gss_add_oid_set_member. Java GSS-API implementations will not contain 583 them. Java's automatic garbage collection and the immutable property 584 of the Oid object eliminates the complicated memory management issues 585 of the C counterpart. 587 When ever a default value for an Object Identifier Set is required, a 588 "null" value can be used. Please consult the detailed method 589 description for details. 591 4.6. Credentials 593 GSS-API credentials are represented with the GSSCredential object. 594 The object contains several constructs to allow for the creation of 595 most common credential objects for the initiator and the acceptor. 596 Comparisons are performed using the object's "equals" method. The 597 following general description of GSS-API credentials is included from 598 the C-bindings specification: 600 GSS-API credentials can contain mechanism-specific principal 601 authentication data for multiple mechanisms. A GSS-API credential is 602 composed of a set of credential-elements, each of which is applicable 603 to a single mechanism. A credential may contain at most one 604 credential-element for each supported mechanism. A credential-element 605 identifies the data needed by a single mechanism to authenticate a 606 single principal, and conceptually contains two credential-references 607 that describe the actual mechanism-specific authentication data, one 608 to be used by GSS-API for initiating contexts, and one to be used 609 for accepting contexts. For mechanisms that do not distinguish 610 between acceptor and initiator credentials, both references would 611 point to the same underlying mechanism-specific authentication data. 613 Credentials describe a set of mechanism-specific principals, and give 614 their holder the ability to act as any of those principals. All 615 principal identities asserted by a single GSS-API credential should 616 belong to the same entity, although enforcement of this property is 617 an implementation-specific matter. A single GSSCredential object 618 represents all the credential elements that have been acquired. 620 The constructor's for the GSSContext object allow the value of "null" 621 to be specified as their GSSCredential input parameter. This will 622 indicate a desire by the application to act as a default principal. 623 While individual GSS-API implementations are free to determine such 624 default behavior as appropriate to the mechanism, the following 625 default behavior by these routines is recommended for portability: 627 For the initiator side of the context: 629 GSS-API Java Bindings August 1998 631 1) If there is only a single principal capable of initiating 632 security contexts for the chosen mechanism that the 633 application is authorized to act on behalf of, then that 634 principal shall be used, otherwise 636 2) If the platform maintains a concept of a default network- 637 identity for the chosen mechanism, and if the application 638 is authorized to act on behalf of that identity for the 639 purpose of initiating security contexts, then the principal 640 corresponding to that identity shall be used, otherwise 642 3) If the platform maintains a concept of a default local 643 identity, and provides a means to map local identities into 644 network-identities for the chosen mechanism, and if the 645 application is authorized to act on behalf of the network- 646 identity image of the default local identity for the 647 purpose of initiating security contexts using the chosen 648 mechanism, then the principal corresponding to that 649 identity shall be used, otherwise 651 4) A user-configurable default identity should be used. 653 and for the acceptor side of the context 655 1) If there is only a single authorized principal identity 656 capable of accepting security contexts for the chosen 657 mechanism, then that principal shall be used, otherwise 659 2) If the mechanism can determine the identity of the target 660 principal by examining the context-establishment token 661 processed during the accept method, and if the accepting 662 application is authorized to act as that principal for the 663 purpose of accepting security contexts using the chosen 664 mechanism, then that principal identity shall be used, 665 otherwise 667 3) If the mechanism supports context acceptance by any 668 principal, and if mutual authentication was not requested, 669 any principal that the application is authorized to accept 670 security contexts under using the chosen mechanism may be 671 used, otherwise 673 4) A user-configurable default identity shall be used. 675 The purpose of the above rules is to allow security contexts to be 676 established by both initiator and acceptor using the default behavior 677 GSS-API Java Bindings August 1998 679 whenever possible. Applications requesting default behavior are 680 likely to be more portable across mechanisms and implementations than 681 ones that instantiate a GSSCredential representing a specific 682 identity. 684 4.7. Contexts 686 The GSSContext class is used to represent one end of a GSS-API 687 security context, storing state information appropriate to that end 688 of the peer communication, including cryptographic state information. 690 GSSContext class has distinct constructors to allow the creation of 691 an initiator and acceptor side of the contexts. After the context has 692 been instantiated, the initiator may choose to set various context 693 options which will determine the characteristics of the desired 694 security context. When all the application desired characteristics 695 have been set, the initiator will call the init method which will 696 produce a token for consumption by the peer's accept method. It is 697 the responsibility of the application to deliver the authentication 698 token(s) between the peer applications for processing. Upon 699 completion of the context establishment phase, context attributes can 700 be retrieved, by both the initiator and acceptor, using the accessor 701 methods. These will reflect the actual attributes of the established 702 context. At this point the context can be used by the application to 703 apply cryptographic services to its data. 705 4.8. Authentication tokens 707 A token is a caller-opaque type that GSS-API uses to maintain 708 synchronization between each end of the GSS-API security context. The 709 token is a cryptographically protected octet-string, generated by the 710 underlying mechanism at one end of a GSS-API security context for use 711 by the peer mechanism at the other end. Encapsulation (if required) 712 within the application protocol and transfer of the token are the 713 responsibility of the peer applications. 715 Java GSS-API uses byte arrays to represent authentication tokens. 716 Overloaded methods exist which allow the caller to supply input and 717 output streams which will be used for the reading and writing of the 718 token data. 720 4.9. Interprocess tokens 722 Certain GSS-API routines are intended to transfer data between 723 processes in multi-process programs. These routines use a caller- 724 GSS-API Java Bindings August 1998 726 opaque octet-string, generated by the GSS-API in one process for use 727 by the GSS-API in another process. The calling application is 728 responsible for transferring such tokens between processes. Note 729 that, while GSS-API implementors are encouraged to avoid placing 730 sensitive information within interprocess tokens, or to 731 cryptographically protect them, many implementations will be unable 732 to avoid placing key material or other sensitive data within them. 733 It is the application's responsibility to ensure that interprocess 734 tokens are protected in transit, and transferred only to processes 735 that are trustworthy. An interprocess token is represented using a 736 byte array emitted from the export method of the GSSContext class. 737 The receiver of the interprocess token would use a GSSContext 738 constructor to create a new context object from the supplied token. 739 Once a context has been exported, the GSSContext object is 740 invalidated and is no longer available. 742 4.10. Error Reporting 744 RFC 2078 defined the usage of major and minor status values for 745 signaling of GSS-API errors. The major code, also called GSS status 746 code, is used to signal errors at the GSS-API level independent of 747 the underlying mechanism(s). The minor status value or Mechanism 748 status code, is a mechanism defined error value indicating a 749 mechanism specific error code. 751 Java GSS-API uses exceptions implemented by the GSSException class to 752 signal both minor and major error values. Both, mechanism specific 753 errors and GSS-API level errors are signaled through instances of 754 this class. The usage of exceptions replaces the need for major and 755 minor codes to be used within the API calls. GSSException class also 756 contains methods to obtain textual representations for both the major 757 and minor values, which is equivalent to the functionality of 758 gss_display_status. 760 4.10.1. GSS status codes 762 GSS status codes indicate errors that are independent of the 763 underlying mechanism(s) used to provide the security service. The 764 errors that can be indicated via a GSS status code are generic API 765 routine errors (errors that are defined in the GSS-API 766 specification). The Java bindings take advantage of the strong type 767 checking of the Java language, thus eliminating the need for calling 768 errors. 770 A GSS status code indicates a single fatal generic API error from the 771 routine that has thrown the GSSException. Using exceptions announces 772 GSS-API Java Bindings August 1998 774 that a fatal error has occurred during the execution of the method. 775 Several GSS-API routines can also return supplementary status 776 information which indicate non-fatal errors. These are handled as 777 return values since using exceptions is not appropriate for 778 informatory or warning-like information. The methods that are capable 779 of producing supplementary information are limited to the per-message 780 methods of the GSSContext class, namely verifyMIC and unwrap. These 781 methods return an instance of MessageProp class which contains the 782 specific supplementary error information. 784 GSSException object, along with providing the functionality for 785 setting of the various error codes and translating them into textual 786 representation, also contains the definitions of all the numeric 787 error values. The following table lists the definitions of error 788 codes: 790 Table: GSS Status Codes 792 Name Value Meaning 794 BAD_MECH 1 An unsupported mechanism 795 was requested. 797 BAD_NAME 2 An invalid name was supplied. 799 BAD_NAMETYPE 3 A supplied name was of an 800 unsupported type. 802 BAD_BINDINGS 4 Incorrect channel bindings were 803 supplied. 805 BAD_STATUS 5 An invalid status code was 806 supplied. 808 BAD_MIC 6 A token had an invalid MIC. 810 NO_CRED 7 No credentials were supplied, or 811 the credentials were unavailable 812 or inaccessible. 814 NO_CONTEXT 8 Invalid context has been 815 supplied. 817 DEFECTIVE_TOKEN 9 A supplied token was invalid. 819 DEFECTIVE_CREDENTIAL 10 A supplied credential was 820 invalid. 822 GSS-API Java Bindings August 1998 824 CREDENTIALS_EXPIRED 11 The referenced credentials 825 have expired. 827 CONTEXT_EXPIRED 12 The context has expired. 829 FAILURE 13 Miscellaneous failure, 830 unspecified at the GSS-API level. 832 BAD_QOP 14 The quality-of-protection 833 requested could not be provided. 835 UNAUTHORIZED 15 The operation is forbidden by 836 local security policy. 838 UNAVAILABLE 16 The operation or option is 839 unavailable. 841 DUPLICATE_ELEMENT 17 The requested credential 842 element already exists. 844 NAME_NOT_MN 18 The provided name was not a 845 mechanism name. 847 OLD_TOKEN 19 The token's validity period has 848 expired. 850 DUPLICATE_TOKEN 20 The token was a duplicate of an 851 earlier version. 853 The GSS major status code of FAILURE is used to indicate that the 854 underlying mechanism detected an error for which no specific GSS 855 status code is defined. The mechanism-specific status code can 856 provide more details about the error. 858 4.10.2. Mechanism-specific status codes 860 The GSSException thrown from a GSS-API method may originate from the 861 mechanism independent layer or the mechanism specific layer. In the 862 latter case, the exception will be used to indicate not only the 863 major error codes but also the mechanism specific error code. 865 A default value of 0 will be used to represent the absence of the 866 mechanism specific status code. 868 GSS-API Java Bindings August 1998 870 4.10.3. Supplementary status codes 872 Supplementary status codes are confined to the per-message methods of 873 the GSSContext class. Because of the informative nature of these 874 errors it is not appropriate to use exceptions to signal them. 875 Instead, the per-message operations of the GSSContext class return an 876 instance of a MessageProp class which contain supplementary status 877 information. 879 The MessageProp class defines query methods which return boolean 880 values indicating the following supplementary states: 882 Table: Supplementary Status Methods 884 Method Name Meaning when "true" is returned 886 isDuplicateToken The token was a duplicate of an 887 earlier token. 889 isOldToken The token's validity period has 890 expired. 892 isUnseqToken A later token has already been 893 processed. 895 isGapToken An expected per-message token was 896 not received. 898 "true" return value for any of the above methods indicates that the 899 token exhibited the specified property. The application must 900 determine the appropriate course of action for these supplementary 901 values. They are not treated as errors by the GSS-API. 903 4.11. Names 905 A name is used to identify a person or entity. GSS-API authenticates 906 the relationship between a name and the entity claiming the name. 908 Since different authentication mechanisms may employ different 909 namespaces for identifying their principals, GSS-API's naming support 910 is necessarily complex in multi-mechanism environments (or even in 911 some single-mechanism environments where the underlying mechanism 912 supports multiple namespaces). 914 Two distinct conceptual representations are defined for names: 916 GSS-API Java Bindings August 1998 918 1) A GSS-API form represented by instances of the GSSName class: A 919 single GSSName object may contain multiple names from different 920 namespaces, but all names should refer to the same entity. An 921 example of such an internal name would be the name returned from 922 a call to the getName method of the GSSCredential class, when 923 applied to a credential containing credential elements for 924 multiple authentication mechanisms employing different 925 namespaces. This GSSName object will contain a distinct name for 926 the entity for each authentication mechanism. 928 For GSS-API implementations supporting multiple namespaces, 929 GSSName object implementations must contain sufficient 930 information to determine the namespace to which each primitive 931 name belongs. 933 2) Mechanism-specific contiguous byte array and string forms: 934 Different GSSName constructors are provided to handle both byte 935 array and string formats and to accommodate various calling 936 applications and name types. These formats are capable of 937 containing only a single name (from a single namespace). 938 Contiguous string names are always accompanied by an object 939 identifier specifying the namespace to which the name belongs, 940 and their format is dependent on the authentication mechanism 941 that employs that name. The string name forms are assumed to be 942 printable, and may therefore be used by GSS-API applications for 943 communication with their users. The byte array name formats are 944 assumed to be in non-printable formats (e.g. the byte array 945 returned from the export method of the GSSName class). 947 A GSSName object can be converted to a contiguous representation by 948 using the toString method. This will guarantee that the name will be 949 converted to a printable format. Different constructors for the 950 GSSName object are defined allowing support for multiple syntaxes for 951 each supported namespace, and allowing users the freedom to choose a 952 preferred name representation. The toString method should use an 953 implementation-chosen printable syntax for each supported name-type. 954 To obtain the printable name type, getStringNameType method can be 955 used. 957 There is no guarantee that calling the toString method on a GSSName 958 object will produce the same string form as the original imported 959 string name. Furthermore, it is possible that the name was not even 960 constructed from a string representation. The same applies to name- 961 space identifiers which may not necessarily survive unchanged after a 962 journey through the internal name-form. An example of this might be 963 a mechanism that authenticates X.500 names, but provides an 964 algorithmic mapping of Internet DNS names into X.500. That 965 mechanism's implementation of GSSName might, when presented with a 966 GSS-API Java Bindings August 1998 968 DNS name, generate an internal name that contained both the original 969 DNS name and the equivalent X.500 name. Alternatively, it might only 970 store the X.500 name. In the latter case, the toString method of 971 GSSName would most likely generate a printable X.500 name, rather 972 than the original DNS name. 974 The context acceptor can obtain an instance of GSSName representing 975 the entity performing the context initiation (through the usage of 976 getSrcName method). Since this name has been authenticated by a 977 single mechanism, it contains only a single name (even if the 978 internal name presented by the context initiator to the GSSContext 979 object had multiple components). Such names are termed internal 980 mechanism names, or "MN"s and the names emitted by GSSContext class 981 in the getSrcName and getTargName are always of this type. Since 982 some applications may require MNs without wanting to incur the 983 overhead of an authentication operation, a set of constructors is 984 provided which take not only the name buffer and name type, but also 985 the mechanism oid for which this name should be created. When 986 dealing with an existing GSSName object, the canonicalize method may 987 be invoked to convert a general internal name into an MN. 989 GSSName objects can be compared using their equal method, which 990 returns "true" if the two names being compared refer to the same 991 entity. This is the preferred way to perform name comparisons instead 992 of using the printable names that a given GSS-API implementation may 993 support. Since GSS-API assumes that all primitive names contained 994 within a given internal name refer to the same entity, equal can 995 return "true" if the two names have at least one primitive name in 996 common. If the implementation embodies knowledge of equivalence 997 relationships between names taken from different namespaces, this 998 knowledge may also allow successful comparisons of internal names 999 containing no overlapping primitive elements. 1001 When used in large access control lists, the overhead of creating a 1002 GSSName on each name and invoking the equal method on each name from 1003 the ACL may be prohibitive. As an alternative way of supporting this 1004 case, GSS-API defines a special form of the contiguous byte array 1005 name which may be compared directly (byte by byte). Contiguous names 1006 suitable for comparison are generated by the export method, which 1007 requires that the GSSName represent a MN. Exported names may be re- 1008 imported by using the byte array constructor and specifying the 1009 NT_EXPORT_NAME as the name type object identifier. The resulting 1010 GSSName name will also be a MN. The GSSName object defines public 1011 static Oid objects representing the standard name types. 1012 Structurally, an exported name object consists of a header containing 1013 an OID identifying the mechanism that authenticated the name, and a 1014 trailer containing the name itself, where the syntax of the trailer 1015 is defined by the individual mechanism specification. Detailed 1016 GSS-API Java Bindings August 1998 1018 description of the format is specified in the language-independent 1019 GSS-API specification [GSSAPIv2]. 1021 Note that the results obtained by using the equal method will in 1022 general be different from those obtained by invoking canonicalize and 1023 export, and then comparing the byte array output. The first series 1024 of operation determines whether two (unauthenticated) names identify 1025 the same principal; the second whether a particular mechanism would 1026 authenticate them as the same principal. These two operations will 1027 in general give the same results only for MNs. 1029 It is important to note that the above are guidelines as how GSSName 1030 objects should behave, and are not intended to be specific 1031 requirements of how names objects must be implemented. The mechanism 1032 designers are free to decide on the details of their implementations 1033 of the GSSName object as long as the behavior satisfies the above 1034 guidelines. 1036 4.12. Channel Bindings 1038 GSS-API supports the use of user-specified tags to identify a given 1039 context to the peer application. These tags are intended to be used 1040 to identify the particular communications channel that carries the 1041 context. Channel bindings are communicated to the GSS-API using the 1042 ChannelBinding object. The application may use byte arrays to specify 1043 the application data to be used in the channel binding as well as 1044 using instances of the InetAddress. The InetAddress for the initiator 1045 and/or acceptor can be used within an instance of a ChannelBinding. 1046 ChannelBinding can be set for the GSSContext object using the 1047 setChannelBinding method before the first call to init or accept has 1048 been performed. Unless the setChannelBinding method has been used to 1049 set the ChannelBinding for an instance of GSSContext method, "null" 1050 ChannelBinding will be assumed. InetAddress is currently the only 1051 address type defined within the Java platform and as such, it is the 1052 only one supported within the ChannelBinding class. 1054 Conceptually, the GSS-API concatenates the initiator and acceptor 1055 address information, and the application supplied byte array to form 1056 an octet string. The mechanism calculates a MIC over this octet 1057 string and binds the MIC to the context establishment token emitted 1058 by init method of the GSSContext class. The same bindings are set by 1059 the context acceptor for its GSSContext object and during processing 1060 of the accept method a MIC is calculated in the same way. The 1061 calculated MIC is compared with that found in the token, and if the 1062 MICs differ, accept will throw a GSSException with the major code 1063 set to BAD_BINDINGS, and the context will not be established. Some 1064 mechanisms may include the actual channel binding data in the token 1065 GSS-API Java Bindings August 1998 1067 (rather than just a MIC); applications should therefore not use 1068 confidential data as channel-binding components. 1070 Individual mechanisms may impose additional constraints on addresses 1071 that may appear in channel bindings. For example, a mechanism may 1072 verify that the initiator address field of the channel binding 1073 contains the correct network address of the host system. Portable 1074 applications should therefore ensure that they either provide correct 1075 information for the address fields, or omit setting of the addressing 1076 information. 1078 4.13. Stream Objects 1080 The GSSContext object provides overloaded methods which use input and 1081 output streams as the means to convey authentication and per-message 1082 GSS-API tokens. It is important to note that the streams are expected 1083 to contain the usual GSS-API tokens which would otherwise be handled 1084 through the usage of byte arrays. The tokens are expected to have a 1085 definite start and an end. The callers are responsible for ensuring 1086 that the supplied streams will not block, or expect to block until a 1087 full token is processed by the GSS-API method. Only a single GSS-API 1088 token will be processed per invocation of the stream based method. 1090 The usage of streams allows the callers to have control and 1091 management of the supplied buffers. Because streams are non-primitive 1092 objects, the callers can make the streams as complicated or as simple 1093 as desired simply by using the streams defined in the java.io package 1094 or creating their own through the use of inheritance. This will allow 1095 for the application's greatest flexibility. 1097 4.14. Optional Parameters 1099 Whenever the application wishes to omit an optional parameter the 1100 "null" value shall be used. The detailed method descriptions 1101 indicate which parameters are optional. Methods overloading has also 1102 been used as a technique to indicate default parameters. 1104 5. Additional Controls 1106 This section discusses the optional services that a context initiator 1107 may request of the GSS-API before the context establishment. Each of 1108 these services is requested by calling the appropriate mutator method 1109 in the GSSContext object before the first call to init is performed. 1111 GSS-API Java Bindings August 1998 1113 Only the context initiator can request context flags. 1115 The optional services defined are: 1117 Delegation 1118 The (usually temporary) transfer of rights from initiator to 1119 acceptor, enabling the acceptor to authenticate itself as an 1120 agent of the initiator. 1122 Mutual Authentication 1123 In addition to the initiator authenticating its identity to the 1124 context acceptor, the context acceptor should also authenticate 1125 itself to the initiator. 1127 Replay Detection 1128 In addition to providing message integrity services, GSSContext 1129 per-message operations of getMIC and wrap should include message 1130 numbering information to enable verifyMIC and unwrap to detect 1131 if a message has been duplicated. 1133 Out-of-Sequence Detection 1134 In addition to providing message integrity services, GSSContext 1135 per-message operations (getMIC and wrap) should include message 1136 sequencing information to enable verifyMIC and unwrap to detect 1137 if a message has been received out of sequence. 1139 Anonymous Authentication 1140 The establishment of the security context should not reveal the 1141 initiator's identity to the context acceptor. 1143 Some mechanisms may not support all optional services, and some 1144 mechanisms may only support some services in conjunction with others. 1145 The GSSContext class offers query methods to allow the verification 1146 by the calling application of which services will be available from 1147 the context when the establishment phase is complete. In general, if 1148 the security mechanism is capable of providing a requested service, 1149 it should do so even if additional services must be enabled in order 1150 to provide the requested service. If the mechanism is incapable of 1151 providing a requested service, it should proceed without the service 1152 leaving the application to abort the context establishment process if 1153 it considers the requested service to be mandatory. 1155 Some mechanisms may specify that support for some services is 1156 optional, and that implementors of the mechanism need not provide it. 1157 This is most commonly true of the confidentiality service, often 1158 because of legal restrictions on the use of data-encryption, but may 1159 apply to any of the services. Such mechanisms are required to send 1160 at least one token from acceptor to initiator during context 1161 GSS-API Java Bindings August 1998 1163 establishment when the initiator indicates a desire to use such a 1164 service, so that the initiating GSS-API can correctly indicate 1165 whether the service is supported by the acceptor's GSS-API. 1167 5.1. Delegation 1169 The GSS-API allows delegation to be controlled by the initiating 1170 application via the requestCredDeleg method before the first call to 1171 init has been issued. Some mechanisms do not support delegation, and 1172 for such mechanisms attempts by an application to enable delegation 1173 are ignored. 1175 The acceptor of a security context, for which the initiator enabled 1176 delegation, can check if delegation was enabled by using the 1177 getCredDelegState method of the GSSContext class. In cases when it 1178 is, the delegated credential object can be obtained by calling the 1179 getDelegCred method. The obtained GSSCredential object may then be 1180 used to initiate subsequent GSS-API security contexts as an agent or 1181 delegate of the initiator. If the original initiator's identity is 1182 "A" and the delegate's identity is "B", then, depending on the 1183 underlying mechanism, the identity embodied by the delegated 1184 credential may be either "A" or "B acting for A". 1186 For many mechanisms that support delegation, a simple boolean does 1187 not provide enough control. Examples of additional aspects of 1188 delegation control that a mechanism might provide to an application 1189 are duration of delegation, network addresses from which delegation 1190 is valid, and constraints on the tasks that may be performed by a 1191 delegate. Such controls are presently outside the scope of the GSS- 1192 API. GSS-API implementations supporting mechanisms offering 1193 additional controls should provide extension routines that allow 1194 these controls to be exercised (perhaps by modifying the initiator's 1195 GSS-API credential object prior to its use in establishing a 1196 context). However, the simple delegation control provided by GSS-API 1197 should always be able to over-ride other mechanism-specific 1198 delegation controls. If the application instructs the GSSContext 1199 object that delegation is not desired, then the implementation must 1200 not permit delegation to occur. This is an exception to the general 1201 rule that a mechanism may enable services even if they are not 1202 requested - delegation may only be provided at the explicit request 1203 of the application. 1205 5.2. Mutual Authentication 1207 Usually, a context acceptor will require that a context initiator 1208 authenticate itself so that the acceptor may make an access-control 1209 GSS-API Java Bindings August 1998 1211 decision prior to performing a service for the initiator. In some 1212 cases, the initiator may also request that the acceptor authenticate 1213 itself. GSS-API allows the initiating application to request this 1214 mutual authentication service by calling the requestMutualAuth method 1215 of the GSSContext class with a "true" parameter before making the 1216 first call to init. The initiating application is informed as to 1217 whether or not the context acceptor has authenticated itself. Note 1218 that some mechanisms may not support mutual authentication, and other 1219 mechanisms may always perform mutual authentication, whether or not 1220 the initiating application requests it. In particular, mutual 1221 authentication may be required by some mechanisms in order to support 1222 replay or out-of-sequence message detection, and for such mechanisms 1223 a request for either of these services will automatically enable 1224 mutual authentication. 1226 5.3. Replay and Out-of-Sequence Detection 1228 The GSS-API may provide detection of mis-ordered messages once a 1229 security context has been established. Protection may be applied to 1230 messages by either application, by calling either getMIC or wrap 1231 methods of the GSSContext class, and verified by the peer application 1232 by calling verifyMIC or unwrap for the peer's GSSContext object. 1234 getMIC calculates a cryptographic checksum of an application message, 1235 and returns that checksum in a token. The application should pass 1236 both the token and the message to the peer application, which 1237 presents them to the verifyMIC method of the peer's GSSContext 1238 object. 1240 wrap calculates a cryptographic checksum of an application message, 1241 and places both the checksum and the message inside a single token. 1242 The application should pass the token to the peer application, which 1243 presents it to the unwrap method of the peer's GSSContext object to 1244 extract the message and verify the checksum. 1246 Either pair of routines may be capable of detecting out-of-sequence 1247 message delivery, or duplication of messages. Details of such mis- 1248 ordered messages are indicated through supplementary query methods of 1249 the MessageProp object returned from each of these routines. 1251 A mechanism need not maintain a list of all tokens that have been 1252 processed in order to support these status codes. A typical 1253 mechanism might retain information about only the most recent "N" 1254 tokens processed, allowing it to distinguish duplicates and missing 1255 tokens within the most recent "N" messages; the receipt of a token 1256 older than the most recent "N" would result in a isOldToken method of 1257 the instance of MessageProp to return "true". 1259 GSS-API Java Bindings August 1998 1261 5.4. Anonymous Authentication 1263 In certain situations, an application may wish to initiate the 1264 authentication process to authenticate a peer, without revealing its 1265 own identity. As an example, consider an application providing 1266 access to a database containing medical information, and offering 1267 unrestricted access to the service. A client of such a service might 1268 wish to authenticate the service (in order to establish trust in any 1269 information retrieved from it), but might not wish the service to be 1270 able to obtain the client's identity (perhaps due to privacy concerns 1271 about the specific inquiries, or perhaps simply to avoid being placed 1272 on mailing-lists). 1274 In normal use of the GSS-API, the initiator's identity is made 1275 available to the acceptor as a result of the context establishment 1276 process. However, context initiators may request that their identity 1277 not be revealed to the context acceptor. Many mechanisms do not 1278 support anonymous authentication, and for such mechanisms the request 1279 will not be honored. An authentication token will still be 1280 generated, but the application is always informed if a requested 1281 service is unavailable, and has the option to abort context 1282 establishment if anonymity is valued above the other security 1283 services that would require a context to be established. 1285 In addition to informing the application that a context is 1286 established anonymously (via the isAnonymous method of the GSSContext 1287 class), the getSrcName method of the acceptor's GSSContext object 1288 will, for such contexts, return a reserved internal-form name, 1289 defined by the implementation. 1291 The toString method for a GSSName object representing an anonymous 1292 entity will return a printable name. The returned value will be 1293 syntactically distinguishable from any valid principal name supported 1294 by the implementation. The associated name-type object identifier 1295 will be an oid representing the value of NT_ANONYMOUS. This name-type 1296 oid will be defined as a public, static Oid object of the GSSName 1297 class. The printable form of an anonymous name should be chosen such 1298 that it implies anonymity, since this name may appear in, for 1299 example, audit logs. For example, the string "" might be 1300 a good choice, if no valid printable names supported by the 1301 implementation can begin with "<" and end with ">". 1303 When using the equal method of the GSSName class, and one of the 1304 operands is a GSSName instance representing an anonymous entity, the 1305 method must return "false". 1307 GSS-API Java Bindings August 1998 1309 5.5. Confidentiality 1311 If a GSSContext supports the confidentiality service, wrap method may 1312 be used to encrypt application messages. Messages are selectively 1313 encrypted, under the control of the setPrivacy method of the 1314 MessageProp object used within the wrap method. 1316 5.6. Inter-process Context Transfer 1318 GSS-API V2 provides functionality which allows a security context to 1319 be transferred between processes on a single machine. These are 1320 implemented using the export method of GSSContext and a byte array 1321 constructor of the same class. The most common use for such a 1322 feature is a client-server design where the server is implemented as 1323 a single process that accepts incoming security contexts, which then 1324 launches child processes to deal with the data on these contexts. In 1325 such a design, the child processes must have access to the security 1326 context object created within the parent so that they can use per- 1327 message protection services and delete the security context when the 1328 communication session ends. 1330 Since the security context data structure is expected to contain 1331 sequencing information, it is impractical in general to share a 1332 context between processes. Thus GSSContext class provides an export 1333 method that the process, which currently owns the context, can call 1334 to declare that it has no intention to use the context subsequently, 1335 and to create an inter-process token containing information needed by 1336 the adopting process to successfully re-create the context. After 1337 successful completion of export, the original security context is 1338 made inaccessible to the calling process by GSS-API and any further 1339 usage of this object will result in failures. The originating 1340 process transfers the inter-process token to the adopting process, 1341 which creates a new GSSContext object using the byte array 1342 constructor. The properties of the context are equivalent to that of 1343 the original context. 1345 The inter-process token may contain sensitive data from the original 1346 security context (including cryptographic keys). Applications using 1347 inter-process tokens to transfer security contexts must take 1348 appropriate steps to protect these tokens in transit. 1350 Implementations are not required to support the inter-process 1351 transfer of security contexts. Calling the isTransferable method of 1352 the GSSContext class will indicate if the context object is 1353 transferable. 1355 GSS-API Java Bindings August 1998 1357 5.7. The Use of Incomplete Contexts 1359 Some mechanisms may allow the per-message services to be used before 1360 the context establishment process is complete. For example, a 1361 mechanism may include sufficient information in its initial context- 1362 level tokens for the context acceptor to immediately decode messages 1363 protected with wrap or getMIC. For such a mechanism, the initiating 1364 application need not wait until subsequent context-level tokens have 1365 been sent and received before invoking the per-message protection 1366 services. 1368 An application can invoke the isProtReady method of the GSSContext 1369 class to determine if the per-message services are available in 1370 advance of complete context establishment. Applications wishing to 1371 use per-message protection services on partially-established contexts 1372 should query this method before attempting to invoke wrap or getMIC. 1374 6. Detailed GSS-API Class Description 1376 This section lists a detailed description of all the public methods 1377 that each of the GSS-API classes must provide. 1379 6.1. public class GSSName 1381 An object of this class encapsulates a single GSS-API principal 1382 entity. Different name formats and their definitions are identified 1383 with universal Object Identifiers (Oids). The format of the names can 1384 be derived based on the unique oid of each name type. 1386 6.1.1. Example Code 1388 Included below are code examples utilizing the GSSName object. The 1389 code below creates a GSSName object, converts it to a mechanism name 1390 (MN), performs a comparison, obtains a printable representation of 1391 the name, exports it and then re-imports to obtain a new GSSName 1392 object. 1394 //create an oid object for Kerberos v5 1395 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 1397 //create a service name, and convert it to a mechanism name 1398 GSSName aName = new GSSName("service@host", 1399 GSSName.NT_HOSTBASED_SERVICE); 1401 GSS-API Java Bindings August 1998 1403 GSSName mechName = aName.canonicalize(krb5); 1405 //the above two steps are equivalent to the following constructor 1406 GSSName mechName = new GSSName("service@host", 1407 GSSName.NT_HOSTBASED_SERVICE, 1408 krb5); 1410 //perform name comparison 1411 if (aName.equals(mechName)) 1412 print("Names are equals."); 1414 //obtain textual representation of name and its printable 1415 //name type 1416 print(mechName.toString() + 1417 mechName.getStringNameType().toString()); 1419 //export and re-import the name 1420 byte [] exportName = mechName.export(); 1422 //create a new name object from the exported buffer 1423 GSSName newName = new GSSName(exportName, 1424 GSSName.NT_EXPORT_NAME); 1426 6.1.2. Class Constants 1428 public static final Oid NT_HOSTBASED_SERVICE 1430 Oid indicating a host-based service name form. It is used to 1431 represent services associated with host computers. This name form is 1432 constructed using two elements, "service" and "hostname", as follows: 1434 service@hostname 1436 Values for the "service" element are registered with the IANA. It 1437 represents the following value: { 1(iso), 3(org), 6(dod), 1438 1(internet), 5(security), 6(nametypes), 2(gss-host-based-services) } 1440 public static final Oid NT_USER_NAME 1442 Name type to indicate a named user on a local system. It represents 1443 the following value: { iso(1) member-body(2) United States(840) 1444 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 1445 GSS-API Java Bindings August 1998 1447 public static final Oid NT_MACHINE_UID_NAME 1449 Name type to indicate a numeric user identifier corresponding to a 1450 user on a local system. (e.g. Uid). It represents the following 1451 value: { iso(1) member-body(2) United States(840) mit(113554) 1452 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 1454 public static final Oid NT_STRING_UID_NAME 1456 Name type to indicate a string of digits representing the numeric 1457 user identifier of a user on a local system. It represents the 1458 following value: { iso(1) member-body(2) United States(840) 1459 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 1461 public static final Oid NT_ANONYMOUS 1463 Name type for representing an anonymous entity. It represents the 1464 following value: { 1(iso), 3(org), 6(dod), 1(internet), 5(security), 1465 6(nametypes), 3(gss-anonymous-name) } 1467 public static final Oid NT_EXPORT_NAME 1469 Name type used to indicate an exported name produced by the export 1470 method. It represents the following value: { 1(iso), 3(org), 6(dod), 1471 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) } 1473 6.1.3. Constructors 1475 public GSSName(String nameStr, Oid type) throws GSSException 1477 Converts a contiguous string name to a GSSName object of the 1478 specified type. The nameStr parameter is interpreted based on the 1479 type specified. In general, the GSSName object created will not be 1480 an MN; the exception to this is if the type parameter indicates 1481 NT_EXPORT_NAME. 1483 Parameters: 1485 nameStr The string representing the name to create. 1487 type Oid specifying type of the printable name supplied. 1488 "null" value can be used to specify a default 1489 printable syntax. 1491 GSS-API Java Bindings August 1998 1493 public GSSName(byte name[], Oid type) throws GSSException 1495 Converts a contiguous byte name to a GSSName object of the specified 1496 type. The name parameter is interpreted based on the type specified. 1497 This constructor is provided for use with names that aren't expressed 1498 as printable strings (for example, names of type NT_EXPORT_NAME). In 1499 general, the GSSName object created will not be an MN. 1501 Parameters: 1503 name The byte array representing the name to create. 1505 type Oid specifying the type of name supplied. "null" value 1506 can be used to specify a default syntax. 1508 public GSSName(String nameStr, Oid nameType, Oid mechType) 1509 throws GSSException 1511 Converts a contiguous string name to a GSSName object of the 1512 specified type. The nameStr parameter is interpreted based on the 1513 type specified. This constructor is provided to allow the creation of 1514 mechanism-specific names without having to call canonicalize. 1516 Parameters: 1518 nameStr The string representing the name to create. 1520 nameType Oid specifying type of the printable name supplied. 1521 "null" value can be used to specify a default 1522 printable syntax. 1524 mechType Oid specifying the mechanism for which this name 1525 should be created. "null" value can be used to specify 1526 the default mechanism. 1528 public GSSName(byte name[], Oid nameType, Oid mechType) 1529 throws GSSException 1531 Converts a contiguous byte name to a GSSName object of the specified 1532 type. The name parameter is interpreted based on the type specified. 1533 This constructor is provided to be used with names that aren't 1534 expressed as printable strings. It allows the creation of 1535 mechanism-specific names without having to call canonicalize. 1537 Parameters: 1539 GSS-API Java Bindings August 1998 1541 name The byte array representing the name to create. 1543 type Oid specifying the type of name supplied. "null" value 1544 can be used to specify a default syntax. 1546 mechType Oid specifying the mechanism for which this name 1547 should be created. "null" value can be used to specify 1548 the default mechanism. 1550 6.1.4. equals 1552 public boolean equals(Object another) 1554 Compares two GSSName objects to determine whether they refer to the 1555 same entity. If either of the names is of the NT_ANONYMOUS type, 1556 this call will return "false". 1558 Parameters: 1560 another GSSName object to compare with. 1562 6.1.5. equals 1564 public boolean equals(GSSName another) throws GSSException 1566 A variation of equals method which may throw a GSSException when the 1567 names cannot be compared. If either of the names represents an 1568 anonymous entity, the method will return "false". 1570 Parameters: 1572 another GSSName object to compare with. 1574 6.1.6. canonicalize 1576 public GSSName canonicalize(Oid mechOid) throws GSSException 1578 Creates a mechanism name (MN) from an arbitrary internal name. This 1579 is equivalent to using a constructor which takes the mechanism name 1580 as one of its parameters. 1582 Parameters: 1584 mechOid The oid for the authentication mechanism for which the 1585 canonical form of the name is requested. 1587 GSS-API Java Bindings August 1998 1589 6.1.7. export 1591 public byte[] export() throws GSSException 1593 Returns a canonical contiguous byte representation of a mechanism 1594 name (MN), suitable for direct, byte by byte comparison by 1595 authorization functions. The name must a MN before calling this 1596 method. The format of the header of the outputted buffer is specified 1597 in RFC 2078. 1599 6.1.8. toString 1601 public String toString() 1603 Returns a textual representation of the GSSName object. To retrieve 1604 the printed name format, which determines the syntax of the returned 1605 string, the getStringNameType method can be used. 1607 6.1.9. getStringNameType 1609 public Oid getStringNameType() throws GSSException 1611 Returns the oid representing the type of name returned through the 1612 toString method. Using this oid, the syntax of the printable name can 1613 be determined. 1615 6.1.10. clone 1617 public Object clone() throws CloneNotSupportedException 1619 Creates a duplicate copy of this name. 1621 6.1.11. isAnonymous 1623 public boolean isAnonymous() 1625 Tests if this name object represents an anonymous entity. Returns 1626 "true" if this is an anonymous name. 1628 6.2. public class GSSCredential 1630 This class manages GSS-API credentials and their associated 1631 GSS-API Java Bindings August 1998 1633 operations. A credential contains all the necessary cryptographic 1634 information to enable the creation of a context on behalf of the 1635 entity that it represents. It may contain multiple, distinct, 1636 mechanism specific credential elements, each containing information 1637 for a specific security mechanism, but all referring to the same 1638 entity. 1640 A credential may be used to perform context initiation, acceptance, 1641 or both. 1643 GSS-API implementations must impose a local access-control policy on 1644 callers to prevent unauthorized callers from acquiring credentials to 1645 which they are not entitled. GSSCredential creation is not intended 1646 to provide a "login to the network" function, as such a function 1647 would involve the creation of new credentials rather than merely 1648 acquiring a handle to existing credentials. Such functions, if 1649 required, should be defined in implementation-specific extensions to 1650 the API. 1652 If credential acquisition is time-consuming for a mechanism, the 1653 mechanism may choose to delay the actual acquisition until the 1654 credential is required (e.g. by the GSSContext object). Such 1655 mechanism-specific implementation decisions should be invisible to 1656 the calling application; thus the query methods immediately following 1657 the creation of a credential object must return valid credential 1658 data, and may therefore incur the overhead of a deferred credential 1659 acquisition. 1661 Applications will create a GSSCredential object passing the desired 1662 parameters. The application can then use the query methods to obtain 1663 specific information about the instantiated credential object 1664 (equivalent to the gss_inquire routines). When the credential is no 1665 longer needed, the application should call the dispose (equivalent to 1666 gss_release_cred) method to release any resources held by the 1667 credential object and to destroy any cryptographically sensitive 1668 information. 1670 6.2.1. Example Code 1672 This example code demonstrates the creation of a GSSCredential object 1673 for a specific entity, querying of its fields, and its release when 1674 it is no longer needed. 1676 //start by creating a name object for the entity 1677 GSSName aName = new GSSName("userName", GSSName.NT_USER_NAME); 1679 GSSCredential entity = new GSSCredential( 1680 GSS-API Java Bindings August 1998 1682 aName, 1683 GSSCredential.ACCEPT_ONLY); 1685 //display credential information - name, remaining lifetime, 1686 //and the mechanisms it has been acquired over 1687 print(entity.getGSSName().toString()); 1688 print(entity.getRemainingLifetime()); 1690 Oid [] mechs = entity.getMechs(); 1691 if (mechs != null) { 1692 for (int i = 0; i < mechs.length; i++) 1693 print(mechs[i].toString()); 1694 } 1696 //release system resources held by the credential 1697 entity.dispose(); 1699 6.2.2. Class Constants 1701 public static final int INITIATE_AND_ACCEPT 1703 Credential usage flag requesting that it be able to be used for both 1704 context initiation and acceptance. 1706 public static final int INITIATE_ONLY 1708 Credential usage flag requesting that it be able to be used for 1709 context initiation only. 1711 public static final int ACCEPT_ONLY 1713 Credential usage flag requesting that it be able to be used for 1714 context acceptance only. 1716 public static final int INDEFINITE 1718 A lifetime constant representing indefinite credential lifetime. 1719 This value must be set to the maximum integer value in Java - 1720 Integer.MAX_VALUE. 1722 6.2.3. Constructors 1724 public GSSCredential(int usage) throws GSSException 1725 GSS-API Java Bindings August 1998 1727 Constructor for default credentials. This will use the default 1728 mechanism, name, and an INDEFINITE lifetime. 1730 Parameters are: 1732 usage The intended usage for this credential object. The 1733 value of this parameter must be one of: 1734 GSSCredential.ACCEPT_AND_INITIATE, 1735 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1737 public GSSCredential(GSSName aName, int usage) throws GSSException 1739 Constructor for default mechanism credential. Uses default mechanism 1740 and INDEFINITE lifetime. 1742 Parameters are: 1744 aName Name of the principal for whom this credential is to 1745 be acquired. 1747 usage The intended usage for this credential object. The 1748 value of this parameter must be one of: 1749 GSSCredential.ACCEPT_AND_INITIATE, 1750 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1752 public GSSCredential(GSSName aName, int lifetime, Oid mechOid, 1753 int usage) throws GSSException 1755 Constructor for a single mechanism credential. "null" values can be 1756 specified for name and mechanism to obtain system specific defaults. 1758 Parameters: 1760 aName Name of the principal for whom this credential is to 1761 be acquired. Use "null" to specify the default 1762 principal. 1764 lifetime The number of seconds that credentials should remain 1765 valid. Use GSSCredential.INDEFINITE to request that 1766 the credentials have the maximum permitted lifetime. 1768 mechOid The oid of the desired mechanism. 1770 usage The intended usage for this credential object. The 1771 value of this parameter must be one of: 1772 GSSCredential.ACCEPT_AND_INITIATE, 1773 GSS-API Java Bindings August 1998 1775 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1777 public GSSCredential(GSSName aName, int lifetime, Oid mechs[], 1778 int usage) throws GSSException 1780 Constructor for a credential over a set of mechanisms. Acquires 1781 credentials for each of the mechanisms specified in mechs array. 1782 "null" value can be used for aName to obtain system specific default. 1783 To determine which mechanism's acquisition of the credential was 1784 successful use the getMechs method. This call is equivalent to 1785 creating a single mechanism credential and using addCred to extend 1786 the credential over other mechanisms. 1788 Parameters: 1790 aName Name of the principal for whom this credential is to 1791 be acquired. Use "null" to specify the default 1792 principal. 1794 lifetime The number of seconds that credentials should remain 1795 valid. Use GSSCredential.INDEFINITE to request that 1796 the credentials have the maximum permitted lifetime. 1798 mechOid The array of mechanisms over which the credential is 1799 to be acquired. 1801 usage The intended usage for this credential object. The 1802 value of this parameter must be one of: 1803 GSSCredential.ACCEPT_AND_INITIATE, 1804 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1806 6.2.4. dispose 1808 public void dispose() throws GSSException 1810 Releases any sensitive information that the GSSCredential may be 1811 containing. Applications should call this method as soon as the 1812 credential is no longer needed to minimize the time sensitive 1813 information is maintained. 1815 6.2.5. getGSSName 1817 public GSSName getGSSName() throws GSSException 1819 Retrieves the name of the entity that the credential asserts. 1821 GSS-API Java Bindings August 1998 1823 6.2.6. getGSSName 1825 public GSSName getGSSName(Oid mechOID) throws GSSException 1827 Retrieves per-mechanism name of the entity that the credential 1828 asserts. 1830 Parameters: 1832 mechOID The mechanism for which information should be 1833 returned. 1835 6.2.7. getRemainingLifetime 1837 public int getRemainingLifetime() throws GSSException 1839 Returns the remaining lifetime in seconds for a credential. The 1840 remaining lifetime is the minimum lifetime for any of the underlying 1841 credential mechanisms. A return value of GSSCredential.INDEFINITE 1842 indicates that the credential does not expire. A return value of 0 1843 indicates that the credential is already expired. 1845 6.2.8. getRemainingInitLifetime 1847 public int getRemainingInitLifetime(Oid mech) throws GSSException 1849 Returns the remaining lifetime is seconds for the credential to 1850 remain capable of initiating security contexts under the specified 1851 mechanism. A return value of GSSCredential.INDEFINITE indicates that 1852 the credential does not expire for context initiation. A return value 1853 of 0 indicates that the credential is already expired. 1855 Parameters: 1857 mechOID The mechanism for which information should be 1858 returned. 1860 6.2.9. getRemainingAcceptLifetime 1862 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 1864 Returns the remaining lifetime is seconds for the credential to 1865 remain capable of accepting security contexts under the specified 1866 mechanism. A return value of GSSCredential.INDEFINITE indicates that 1867 the credential does not expire for context acceptance. A return value 1868 GSS-API Java Bindings August 1998 1870 of 0 indicates that the credential is already expired. 1872 Parameters: 1874 mechOID The mechanism for which information should be 1875 returned. 1877 6.2.10. getUsage 1879 public int getUsage() throws GSSException 1881 Returns the credential usage flag. The return value will be one of 1882 GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or 1883 GSSCredential.INITIATE_AND_ACCEPT. 1885 6.2.11. getUsage 1887 public int getUsage(Oid mechOID) throws GSSException 1889 Returns the credential usage flag for the specified credential 1890 mechanism. The return value will be one of 1891 GSSCredential.INITIATE_ONLY, GSSCredential.ACCEPT_ONLY, or 1892 GSSCredential.INITIATE_AND_ACCEPT. 1894 Parameters: 1896 mechOID The mechanism for which information should be 1897 returned. 1899 6.2.12. getMechs 1901 public Oid[] getMechs() throws GSSException 1903 Returns an array of mechanisms supported by this credential. 1905 6.2.13. add 1907 public void add(GSSName aName, int initLifetime, int acceptLifetime, 1908 Oid mech, int usage) throws GSSException 1910 Adds a mechanism specific credential-element to an existing 1911 credential. This method allows the construction of credentials one 1912 mechanism at a time. This functionality is equivalent to using the 1913 GSSCredential constructor which takes an Oid array as an input 1914 GSS-API Java Bindings August 1998 1916 parameter or calling this method once for each of the mechanisms in 1917 the array. 1919 This routine is envisioned to be used mainly by context acceptors 1920 during the creation of acceptance credentials which are to be used 1921 with a variety of clients using different security mechanisms. 1923 To obtain a new credential object after the addition of the new 1924 mechanism credential, the clone method can be called. 1926 Parameters: 1928 aName Name of the principal for whom this credential is to 1929 be acquired. Use "null" to specify the default 1930 principal. 1932 initLifetime 1933 The number of seconds that credentials should remain 1934 valid for initiating of security contexts. Use 1935 GSSCredential.INDEFINITE to request that the 1936 credentials have the maximum permitted lifetime. 1938 acceptLifetime 1939 The number of seconds that credentials should remain 1940 valid for accepting of security contexts. Use 1941 GSSCredential.INDEFINITE to request that the 1942 credentials have the maximum permitted lifetime. 1944 mechOid The mechanisms over which the credential is to be 1945 acquired. 1947 usage The intended usage for this credential object. The 1948 value of this parameter must be one of: 1949 GSSCredential.ACCEPT_AND_INITIATE, 1950 GSSCredential.ACCEPT_ONLY, GSSCredential.INITIATE_ONLY 1952 6.2.14. equals 1954 public boolean equals(Object another) 1956 Tests if this GSSCredential refers to the same entity as the supplied 1957 object. The two GSSCredentials must be acquired over the same 1958 mechanisms and must refer to the same principal. Returns "true" if 1959 the two GSSCredentials refer to the same entity; "false" otherwise. 1961 Parameter: 1963 GSS-API Java Bindings August 1998 1965 another Another GSSCredential object for comparison. 1967 6.3. public class GSSContext 1969 This class represents the GSS-API security context and its associated 1970 operations. Security contexts are established between peers using 1971 locally acquired credentials. Multiple contexts may exist 1972 simultaneously between a pair of peers, using the same or different 1973 set of credentials. GSS-API functions in a manner independent of the 1974 underlying transport protocol and depends on its calling application 1975 to transport its tokens between peers. 1977 The GSSContext object can be thought of as having 3 implicit states: 1978 before it is established, during its context establishment, and after 1979 a fully established context exists. 1981 Before the context establishment phase is initiated, the context 1982 initiator may request specific characteristics desired of the 1983 established context. These can be set using the set methods. After 1984 the context is established, the caller can check the actual 1985 characteristic and services offered by the context using the query 1986 methods. 1988 The context establishment phase begins with the first call to the 1989 init method by the context initiator. During this phase the init and 1990 accept methods will produce GSS-API authentication tokens which the 1991 calling application needs to send to its peer. The init and accept 1992 methods may return a CONTINUE_NEEDED code which indicates that a 1993 token is needed from its peer in order to continue the context 1994 establishment phase. A return code of COMPLETE signals that the local 1995 end of the context is established. This may still require that a 1996 token be sent to the peer, depending if one is produced by GSS-API. 1997 The isEstablished method can also be used to determine if the local 1998 end of the context has been fully established. During the context 1999 establishment phase, the isProtReady method may be called to 2000 determine if the context can be used for the per-message operations. 2001 This allows implementation to use per-message operations on contexts 2002 which aren't fully established. 2004 After the context has been established or the isProtReady method 2005 returns "true", the query routines can be invoked to determine the 2006 actual characteristics and services of the established context. The 2007 application can also start using the per-message methods of wrap and 2008 getMIC to obtain cryptographic operations on application supplied 2009 data. 2011 GSS-API Java Bindings August 1998 2013 When the context is no longer needed, the application should call 2014 dispose to release any system resources the context may be using. 2016 6.3.1. Example Code 2018 The example code presented below demonstrates the usage of the 2019 GSSContext object for the initiating peer. Different operations on 2020 the GSSContext object are presented, including: object instantiation, 2021 setting of desired flags, context establishment, query of actual 2022 context flags, per-message operations on application data, and 2023 finally context deletion. 2025 //start by creating the name for a service entity 2026 GSSName targetName = new GSSName("service@host", 2027 GSSName.NT_HOSTBASED_SERVICE); 2029 //create a context using default credentials for the 2030 //default mechanism 2031 GSSContext aCtxt = new GSSContext(targetName, 2032 null, /* default mechanism */ 2033 null, /* default credentials */ 2034 GSSContext.INDEFINITE); 2036 //set desired context options - all others are false by default 2037 aCtxt.requestConf(true); 2038 aCtxt.requestMutualAuth(true); 2039 aCtxt.requestReplayDet(true); 2040 aCtxt.requestSequenceDet(true); 2042 //establish a context between peers - using byte arrays 2043 byte []inTok = new byte[0]; 2045 try { 2046 do { 2047 byte[] outTok = aCtxt.init(inTok, 0, inTok.length); 2049 //send the token if present 2050 if (outTok != null) 2051 sendToken(outTok); 2053 //check if we should expect more tokens 2054 if (aCtxt.isEstablished()) 2055 break; 2057 //another token expected from peer 2058 GSS-API Java Bindings August 1998 2060 inTok = readToken(); 2062 } while (true); 2064 } catch (GSSException e) { 2065 print("GSSAPI error: " + e.getMessage()); 2066 } 2068 //display context information 2069 print("Remaining lifetime in seconds = " + aCtxt.getLifetime()); 2070 print("Context mechanism = " + aCtxt.getMech().toString()); 2071 print("Initiator = " + aCtxt.getSrcName().toString()); 2072 print("Acceptor = " + aCtxt.getTargName().toString()); 2074 if (aCtxt.getConfState()) 2075 print("Confidentiality security service available"); 2077 if (aCtxt.getIntegState()) 2078 print("Integrity security service available"); 2080 //perform wrap on an application supplied message, appMsg, 2081 //using QOP = 0, and requesting privacy service 2082 byte [] appMsg ... 2084 MessageProp mProp = new MessageProp(0, true); 2086 byte []tok = aCtxt.wrap(appMsg, 0, appMsg.length, mProp); 2088 if (mProp.getPrivacy()) 2089 print("Message protected with privacy."); 2091 sendToken(tok); 2093 //release the local-end of the context 2094 aCtxt.dispose(); 2096 6.3.2. Class Constants 2098 public static final int INDEFINITE 2100 A lifetime constant representing indefinite context lifetime. This 2101 value must be set to the maximum integer value in Java - 2102 Integer.MAX_VALUE. 2104 GSS-API Java Bindings August 1998 2106 public static final int COMPLETE 2108 Return value from either accept or init stating that the context 2109 creation phase is complete for this peer. 2111 public static final int CONTINUE_NEEDED 2113 Return value from either accept or init stating that another token is 2114 required from the peer to continue context creation. This may be 2115 returned several times indicating multiple token exchanges. 2117 6.3.3. Constructors 2119 public GSSContext(GSSName peer, Oid mechOid, GSSCredential myCred, 2120 int lifetime) throws GSSException 2122 Constructor for creating a context on the initiator's side. Context 2123 flags may be modified through the mutator methods prior to calling 2124 init. 2126 Parameters: 2128 peer Name of the target peer. 2130 mechOid Oid of the desired mechanism. Use "null" to request 2131 the default mechanism. 2133 myCred Credentials of the initiator. Use "null" to act as a 2134 default initiator principal. 2136 lifetime The request lifetime, in seconds, for the credential. 2138 public GSSContext(GSSCredential myCred) throws GSSException 2140 Constructor for creating a context on the acceptor' side. The 2141 context's properties will be determined from the input token supplied 2142 to the accept method. 2144 Parameters: 2146 myCred Credentials for the acceptor. Use "null" to act as a 2147 default acceptor principal. 2149 public GSSContext(byte [] interProcessToken) throws GSSException 2150 GSS-API Java Bindings August 1998 2152 Constructor for creating a previously exported context. The context 2153 properties will be determined from the input token and can't be 2154 modified through the set methods. 2156 Parameters: 2158 interProcessToken 2159 The token previously emitted from the export method. 2161 6.3.4. init 2163 public byte[] init(byte inputBuf[], int offset, int len) 2164 throws GSSException 2166 Called by the context initiator to start the context creation 2167 process. This is equivalent to the stream based method except that 2168 the token buffers are handled as byte arrays instead of using stream 2169 objects. This method may return an output token which the application 2170 will need to send to the peer for processing by the accept call. 2171 "null" return value indicates that no token needs to be sent to the 2172 peer. The application can call isEstablished to determine if the 2173 context establishment phase is complete for this peer. A return value 2174 of "false" from isEstablished indicates that more tokens are expected 2175 to be supplied to the init method. Please note that the init method 2176 may return a token for the peer, and isEstablished return "true" 2177 also. This indicates that the token needs to be sent to the peer, but 2178 the local end of the context is now fully established. 2180 Upon completion of the context establishment, the available context 2181 options may be queried through the get methods. 2183 Parameters: 2185 inputBuf Token generated by the peer. This parameter is ignored 2186 on the first call. 2188 offset The offset within the inputBuf where the token begins. 2190 len The length of the token within the inputBuf (starting 2191 at the offset). 2193 6.3.4.1. Example Code 2195 //create a GSSContext object 2196 GSSContext aCtxt = new GSSContext(... 2198 GSS-API Java Bindings August 1998 2200 byte []inTok = new byte[0]; 2202 try { 2204 do { 2205 byte[] outTok = aCtxt.init(inTok, 0, 2206 inTok.length); 2208 //send the token if present 2209 if (outTok != null) 2210 sendToken(outTok); 2212 //check if we should expect more tokens 2213 if (aCtxt.isEstablished()) 2214 break; 2216 //another token expected from peer 2217 inTok = readToken(); 2218 } while (true); 2220 } catch (GSSException e) { 2221 print("GSSAPI error: " + e.getMessage()); 2222 } 2224 6.3.5. init 2226 public int init(InputStream inputBuf, OutputStream outputBuf) 2227 throws GSSException 2229 Called by the context initiator to start the context creation 2230 process. This is equivalent to the byte array based method. This 2231 method may write an output token to the outputBuf, which the 2232 application will need to send to the peer for processing by the 2233 accept call. 0 bytes written to the output stream indicate that no 2234 token needs to be sent to the peer. The method will return either 2235 COMPLETE or CONTINUE_NEEDED indicating the status of the current 2236 context. A return value of COMPLETE indicates that the context 2237 establishment phase is complete for this peer, while CONTINUE_NEEDED 2238 means that another token is expected from the peer. The isEstablished 2239 method can also be used to determine this state. Note that it is 2240 possible to have a token for the peer while this method returns 2241 COMPLETE. This indicates that the local end of the context is 2242 established, but the token needs to be sent to the peer to complete 2243 the context establishment. 2245 GSS-API Java Bindings August 1998 2247 The GSS-API authentication tokens contain a definitive start and end. 2248 This method will attempt to read one of these tokens per invocation, 2249 and may block on the stream if only part of the token is available. 2251 Upon completion of the context establishment, the available context 2252 options may be queried through the get methods. 2254 Parameters: 2256 inputBuf Contains the token generated by the peer. This 2257 parameter is ignored on the first call. 2259 outputBuf Buffer where the output token will be written. During 2260 the final stage of context establishment, there may be 2261 no bytes written. 2263 6.3.5.1. Example Code 2265 //create a GSSContext object 2266 GSSContext aCtxt = new GSSContext(... 2268 //use standard java.io stream objects 2269 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2270 ByteArrayInputStream is = null; 2272 try { 2274 while (aCtxt.init(is, os) == 2275 GSSContext.CONTINUE_NEEDED) { 2277 //send token to peer 2278 sendToken(os); 2280 //another token expected from peer 2281 is = recvToken(); 2282 } 2284 //send token if present 2285 if (os.size() > 0) 2286 sendToken(os); 2288 } catch (GSSException e) { 2289 print("GSS-API error: " + e.getMessage()); 2290 } 2291 GSS-API Java Bindings August 1998 2293 6.3.6. accept 2295 public byte[] accept(byte inTok[], int offset, int len) 2296 throws GSSException 2298 Called by the context acceptor upon receiving a token from the peer. 2299 This call is equivalent to the stream based method except that the 2300 token buffers are handled as byte arrays instead of using stream 2301 objects. 2303 This method may return an output token which the application will 2304 need to send to the peer for further processing by the init call. 2305 "null" return value indicates that no token needs to be sent to the 2306 peer. The application can call isEstablished to determine if the 2307 context establishment phase is complete for this peer. A return value 2308 of "false" from isEstablished indicates that more tokens are expected 2309 to be supplied to this method. 2311 Please note that the accept method may return a token for the peer, 2312 and isEstablished return "true" also. This indicates that the token 2313 needs to be sent to the peer, but the local end of the context is now 2314 fully established. 2316 Upon completion of the context establishment, the available context 2317 options may be queried through the get methods. 2319 Parameters: 2321 inTok Token generated by the peer. 2323 offset The offset within the inTok where the token begins. 2325 len The length of the token within the inTok (starting at 2326 the offset). 2328 6.3.6.1. Example Code 2330 //obtain server credentials 2331 GSSCredential server = ... 2333 //create acceptor GSS-API context 2334 GSSContext aCtxt = new GSSContext(server); 2336 try { 2337 do { 2338 byte [] inTok = readToken(); 2339 GSS-API Java Bindings August 1998 2341 byte []outTok = aCtxt.accept(inTok, 0, 2342 inTok.length); 2344 //possibly send token to peer 2345 if (outTok != null) 2346 sendToken(outTok); 2348 //check if local context establishment is complete 2349 if (aCtxt.isEstablished()) 2350 break; 2351 } while (true); 2353 } catch (GSSException e) { 2354 print("GSS-API error: " + e.getMessage()); 2355 } 2357 6.3.7. accept 2359 public int accept(InputStream inputBuf, OutputStream outputBuf) 2360 throws GSSException 2362 Called by the context acceptor upon receiving a token from the peer. 2363 This call is equivalent to the byte array method. It may write an 2364 output token to the outputBuf, which the application will need to 2365 send to the peer for processing by its init method. 0 bytes written 2366 to the output stream indicate that no token needs to be sent to the 2367 peer. The method will return either COMPLETE or CONTINUE_NEEDED 2368 indicating the status of the current context. A return value of 2369 COMPLETE indicates that the context establishment phase is complete 2370 for this peer, while CONTINUE_NEEDED means that another token is 2371 expected from the peer. The isEstablished method can also be used to 2372 determine this state. Note that it is possible to have a token for 2373 the peer while this method returns COMPLETE. This indicates that the 2374 local end of the context is established, but the token needs to be 2375 sent to the peer to complete the context establishment. 2377 The GSS-API authentication tokens contain a definitive start and end. 2378 This method will attempt to read one of these tokens per invocation, 2379 and may block on the stream if only part of the token is available. 2381 Upon completion of the context establishment, the available context 2382 options may be queried through the get methods. 2384 Parameters: 2386 inputBuf Contains the token generated by the peer. 2388 GSS-API Java Bindings August 1998 2390 outputBuf Buffer where the output token will be written. During 2391 the final stage of context establishment, there may be 2392 no bytes written. 2394 6.3.7.1. Example Code 2396 //obtain server credentials 2397 GSSCredential server = ... 2399 //create acceptor GSS-API context 2400 GSSContext aCtxt = new GSSContext(server); 2402 //use standard java.io stream objects 2403 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2404 ByteArrayInputStream is = null; 2405 int retCode; 2407 try { 2408 do { 2409 is = recvToken(); 2410 retCode = aCtxt.accept(is, os); 2412 //possibly send token to peer 2413 if (os.size() > 0) 2414 sendToken(os); 2416 } while (retCode == GSSContext.CONTINUE_NEEDED); 2418 } catch (GSSException e) { 2419 print("GSS-API error: " + e.getMessage()); 2420 } 2422 6.3.8. isEstablished 2424 public boolean isEstablished() 2426 Returns "true" if this is a fully established context. Used after the 2427 init and accept methods to check if more tokens are needed from the 2428 peer. 2430 6.3.9. dispose 2432 public void dispose() throws GSSException 2433 GSS-API Java Bindings August 1998 2435 Releases any system resources and cryptographic information stored in 2436 the context object. This will invalidate the context. 2438 6.3.10. getWrapSizeLimit 2440 public int getWrapSizeLimit(int qop, boolean confReq, 2441 int maxTokenSize) throws GSSException 2443 Returns the maximum message size that, if presented to the wrap 2444 method with the same confReq and qop parameters, will result in an 2445 output token containing no more than the maxTokenSize bytes. 2447 This call is intended for use by applications that communicate over 2448 protocols that impose a maximum message size. It enables the 2449 application to fragment messages prior to applying protection. 2451 GSS-API implementations are recommended but not required to detect 2452 invalid QOP values when getWrapSizeLimit is called. This routine 2453 guarantees only a maximum message size, not the availability of 2454 specific QOP values for message protection. 2456 Successful completion of this call does not guarantee that wrap will 2457 be able to protect a message of the computed length, since this 2458 ability may depend on the availability of system resources at the 2459 time that wrap is called. However, if the implementation itself 2460 imposes an upper limit on the length of messages that may be 2461 processed by wrap, the implementation should not return a value that 2462 is greater than this length. 2464 Parameters: 2466 qop Indicates the level of protection wrap will be asked 2467 to provide. 2469 confReq Indicates if wrap will be asked to provide privacy 2470 service. 2472 maxTokenSize 2473 The desired maximum size of the token emitted by wrap. 2475 6.3.11. wrap 2477 public byte[] wrap(byte inBuf[], int offset, int len, 2478 MessageProp msgProp) throws GSSException 2480 Allows to apply per-message security services over the established 2481 GSS-API Java Bindings August 1998 2483 security context. The method will return a token with a cryptographic 2484 MIC and may optionally encrypt the specified inBuf. This method is 2485 equivalent in functionality to its stream counterpart. The returned 2486 byte array will contain both the MIC and the message. The msgProp 2487 object is used to specify a QOP value which selects cryptographic 2488 algorithms, and a privacy service, if supported by the chosen 2489 mechanism. 2491 Since some application-level protocols may wish to use tokens emitted 2492 by wrap to provide "secure framing", implementations should support 2493 the wrapping of zero-length messages. 2495 The application will be responsible for sending the token to the 2496 peer. 2498 Parameters: 2500 inBuf Application data to be protected. 2502 offset The offset within the inBuf where the data begins. 2504 len The length of the data within the inBuf (starting at 2505 the offset). 2507 msgProp Instance of MessageProp containing the desired QOP and 2508 privacy state. Upon return from this method, this 2509 object will contain the applied QOP (for cases when 0 2510 was used) and the actual privacy state of the token. 2512 6.3.12. wrap 2514 public void wrap(InputStream inBuf, OutputStream outBuf, 2515 MessageProp msgProp) throws GSSException 2517 Allows to apply per-message security services over the established 2518 security context. The method will produce a token with a 2519 cryptographic MIC and may optionally encrypt the specified inBuf. 2520 The outBuf will contain both the MIC and the message. The msgProp 2521 object is used to specify a QOP value to select cryptographic 2522 algorithms, and a privacy service, if supported by the chosen 2523 mechanism. 2525 Since some application-level protocols may wish to use tokens emitted 2526 by wrap to provide "secure framing", implementations should support 2527 the wrapping of zero-length messages. 2529 The application will be responsible for sending the token to the 2530 GSS-API Java Bindings August 1998 2532 peer. 2534 Parameters: 2536 inpBuf Application data to be protected. 2538 outBuf The buffer to write the protected message to. The 2539 application is responsible for sending this to the 2540 other peer for processing in its unwrap method. 2542 msgProp Instance of MessageProp containing the desired QOP and 2543 privacy state. Upon return from this method, this 2544 object will contain the applied QOP (for cases when 0 2545 was used) and the actual privacy state of the token. 2547 6.3.13. unwrap 2549 public byte [] unwrap(byte[] inBuf, int offset, int len, 2550 MessageProp msgProp) throws GSSException 2552 Used by the peer application to process tokens generated with the 2553 wrap call. This call is equal in functionality to its stream 2554 counterpart. The method will return the message supplied in the peer 2555 application to the wrap call, verifying the embedded MIC. The 2556 msgProp instance will indicate whether the message was encrypted and 2557 will contain the QOP indicating the strength of protection that was 2558 used to provide the confidentiality and integrity services. 2560 Since some application-level protocols may wish to use tokens emitted 2561 by wrap to provide "secure framing", implementations should support 2562 the wrapping and unwrapping of zero-length messages. 2564 Parameters: 2566 inBuf GSS-API wrap token received from peer. 2568 offset The offset within the inBuf where the token begins. 2570 len The length of the token within the inBuf (starting at 2571 the offset). 2573 msgProp Upon return from the method, this object will contain 2574 the applied QOP and the privacy state of the supplied 2575 token. 2577 GSS-API Java Bindings August 1998 2579 6.3.14. unwrap 2581 public void unwrap(InputStream inBuf, OutputStream outBuf, 2582 MessageProp msgProp) throws GSSException 2584 Used by the peer application to process tokens generated with the 2585 wrap call. This call is equal in functionality to its byte array 2586 counterpart. It will produce the message supplied in the peer 2587 application to the wrap call, verifying the embedded MIC. The 2588 msgProp parameter will indicate whether the message was encrypted and 2589 will contain the QOP indicating the strength of protection that was 2590 used to provide the confidentiality and integrity services. The 2591 msgProp object will also contain the supplementary status information 2592 for the token. 2594 Since some application-level protocols may wish to use tokens emitted 2595 by wrap to provide "secure framing", implementations should support 2596 the wrapping and unwrapping of zero-length messages. 2598 Parameters: 2600 inBuf GSS-API wrap token received from peer. 2602 outBuf The buffer to write the application message to. 2604 msgProp Upon return from the method, this object will contain 2605 the applied QOP, the privacy state, and supplementary 2606 status values for the supplied token. 2608 6.3.15. getMIC 2610 public byte[] getMIC(byte []inMsg, int offset, int len, 2611 MessageProp msgProp) throws GSSException 2613 Returns a token containing a cryptographic MIC for the supplied 2614 message, for transfer to the peer application. Unlike wrap, which 2615 encapsulates the user message in the returned token, only the message 2616 MIC is returned in the output token. This method is identical in 2617 functionality to its stream counterpart. 2619 Note that privacy can only be applied through the wrap call. 2621 Since some application-level protocols may wish to use tokens emitted 2622 by getMIC to provide "secure framing", implementations should support 2623 derivation of MICs from zero-length messages. 2625 Parameters: 2627 GSS-API Java Bindings August 1998 2629 inMsg Message to generate MIC over. 2631 offset The offset within the inMsg where the token begins. 2633 len The length of the token within the inMsg (starting at 2634 the offset). 2636 msgProp Indicates the desired QOP to be used. Use QOP of 0 to 2637 indicate default value. The confidentiality flag is 2638 ignored. Upon return from the method, this object will 2639 contain the applied QOP (in case 0 was selected). 2641 6.3.16. getMIC 2643 public void getMIC(InputStream inMsg, OutputStream outBuf, 2644 MessageProp msgProp) throws GSSException 2646 Produces a token containing a cryptographic MIC for the supplied 2647 message, for transfer to the peer application. Unlike wrap, which 2648 encapsulates the user message in the returned token, only the message 2649 MIC is produced in the output token. This method is identical in 2650 functionality to its byte array counterpart. 2652 Note that privacy can only be applied through the wrap call. 2654 Since some application-level protocols may wish to use tokens emitted 2655 by getMIC to provide "secure framing", implementations should support 2656 derivation of MICs from zero-length messages. 2658 Parameters: 2660 inMsg Buffer containing the message to generate MIC over. 2662 outBuf The buffer to write the GSS-API output token into. 2664 msgProp Indicates the desired QOP to be used. Use QOP of 0 to 2665 indicate default value. The confidentiality flag is 2666 ignored. Upon return from the method, this object will 2667 contain the applied QOP (in case 0 was selected). 2669 6.3.17. verifyMIC 2671 public void verifyMIC(byte []inTok, int tokOffset, int tokLen, 2672 byte[] inMsg, int msgOffset, int msgLen, 2673 MessageProp msgProp) throws GSSException 2675 GSS-API Java Bindings August 1998 2677 Verifies the cryptographic MIC, contained in the token parameter, 2678 over the supplied message. The msgProp parameter will contain the 2679 QOP indicating the strength of protection that was applied to the 2680 message. This method is equivalent in functionality to its stream 2681 counterpart. 2683 Since some application-level protocols may wish to use tokens emitted 2684 by getMIC to provide "secure framing", implementations should support 2685 the calculation and verification of MICs over zero-length messages. 2687 Parameters: 2689 inTok Token generated by peer's getMIC method. 2691 tokOffset The offset within the inTok where the token begins. 2693 tokLen The length of the token within the inTok (starting at 2694 the offset). 2696 inMsg Application message to verify the cryptographic MIC 2697 over. 2699 msgOffset The offset within the inMsg where the message begins. 2701 msgLen The length of the message within the inMsg (starting 2702 at the offset). 2704 msgProp Upon return from the method, this object will contain 2705 the applied QOP and supplementary status values for 2706 the supplied token. The confidentiality state will be 2707 always set to "false". 2709 6.3.18. verifyMIC 2711 public void verifyMIC(InputStream inTok, InputStream inMsg, 2712 MessageProp msgProp) throws GSSException 2714 Verifies the cryptographic MIC, contained in the token parameter, 2715 over the supplied message. The msgProp parameter will contain the 2716 QOP indicating the strength of protection that was applied to the 2717 message. This method is equivalent in functionality to its byte array 2718 counterpart. 2720 Since some application-level protocols may wish to use tokens emitted 2721 by getMIC to provide "secure framing", implementations should support 2722 the calculation and verification of MICs over zero-length messages. 2724 GSS-API Java Bindings August 1998 2726 Parameters: 2728 inTok Contains the token generated by peer's getMIC method. 2730 inMsg Contains application message to verify the 2731 cryptographic MIC over. 2733 msgProp Upon return from the method, this object will contain 2734 the applied QOP and supplementary status values for 2735 the supplied token. The confidentiality state will be 2736 always set to "false". 2738 6.3.19. export 2740 public byte [] export() throws GSSException 2742 Provided to support the sharing of work between multiple processes. 2743 This routine will typically be used by the context-acceptor, in an 2744 application where a single process receives incoming connection 2745 requests and accepts security contexts over them, then passes the 2746 established context to one or more other processes for message 2747 exchange. 2749 This method deactivates the security context and creates an 2750 interprocess token which, when passed to the byte array constructor 2751 of the GSSContext class in another process, will re-activate the 2752 context in the second process. Only a single instantiation of a given 2753 context may be active at any one time; a subsequent attempt by a 2754 context exporter to access the exported security context will fail. 2756 The implementation may constrain the set of processes by which the 2757 interprocess token may be imported, either as a function of local 2758 security policy, or as a result of implementation decisions. For 2759 example, some implementations may constrain contexts to be passed 2760 only between processes that run under the same account, or which are 2761 part of the same process group. 2763 The interprocess token may contain security-sensitive information 2764 (for example cryptographic keys). While mechanisms are encouraged to 2765 either avoid placing such sensitive information within interprocess 2766 tokens, or to encrypt the token before returning it to the 2767 application, in a typical GSS-API implementation this may not be 2768 possible. Thus the application must take care to protect the 2769 interprocess token, and ensure that any process to which the token is 2770 transferred is trustworthy. 2772 GSS-API Java Bindings August 1998 2774 6.3.20. requestMutualAuth 2776 public void requestMutualAuth(boolean state) throws GSSException 2778 Sets the request state of the mutual authentication flag for the 2779 context. This method is only valid before the context creation 2780 process begins and only for the initiator. 2782 Parameters: 2784 state Boolean representing if mutual authentication should 2785 be requested during context establishment. 2787 6.3.21. requestReplayDet 2789 public void requestReplayDet(boolean state) throws GSSException 2791 Sets the request state of the replay detection service for the 2792 context. This method is only valid before the context creation 2793 process begins and only for the initiator. 2795 Parameters: 2797 state Boolean representing if replay detection is desired 2798 over the established context. 2800 6.3.22. requestSequenceDet 2802 public void requestSequenceDet(boolean state) throws GSSException 2804 Sets the request state for the sequence checking service of the 2805 context. This method is only valid before the context creation 2806 process begins and only for the initiator. 2808 Parameters: 2810 state Boolean representing if sequence detection is desired 2811 over the established context. 2813 6.3.23. requestCredDeleg 2815 public void requestCredDeleg(boolean state) throws GSSException 2817 Sets the request state for the credential delegation flag for the 2818 context. This method is only valid before the context creation 2819 GSS-API Java Bindings August 1998 2821 process begins and only for the initiator. 2823 Parameter: 2825 state Boolean representing if credential delegation is 2826 desired. 2828 6.3.24. requestAnonymity 2830 public void requestAnonymity(boolean state) throws GSSException 2832 Requests anonymous support over the context. This method is only 2833 valid before the context creation process begins and only for the 2834 initiator. 2836 Parameter: 2838 state Boolean representing if anonymity support is 2839 requested. 2841 6.3.25. requestConf 2843 public void requestConf(boolean state) throws GSSException 2845 Requests that confidentiality service be available over the context. 2846 This method is only valid before the context creation process begins 2847 and only for the initiator. 2849 Parameters: 2851 state Boolean indicating if confidentiality services are to 2852 be requested for the context. 2854 6.3.26. requestInteg 2856 public void requestInteg(boolean state) throws GSSException 2858 Requests that integrity services be available over the context. This 2859 method is only valid before the context creation process begins and 2860 only for the initiator. 2862 Parameters: 2864 state Boolean indicating if integrity services are to be 2865 requested for the context. 2867 GSS-API Java Bindings August 1998 2869 6.3.27. requestLifetime 2871 public void requestLifetime(int lifetime) throws GSSException 2873 Sets the desired lifetime for the context in seconds. This method is 2874 only valid before the context creation process begins and only for 2875 the initiator. 2877 Parameters: 2879 lifetime The desired context lifetime in seconds. 2881 6.3.28. setChannelBinding 2883 public void setChannelBinding(ChannelBinding cb) throws GSSException 2885 Sets the channel bindings to be used during context establishment. 2886 This method is only valid before the context creation process begins. 2888 Parameters: 2890 cb Channel bindings to be used. 2892 6.3.29. getCredDelegState 2894 public boolean getCredDelegState() 2896 Returns the state of the delegated credentials for the context. When 2897 issued before context establishment is completed or when the 2898 isProtReady method returns "false", it returns the desired state, 2899 otherwise it will indicate the actual state over the established 2900 context. 2902 6.3.30. getMutualAuthState 2904 public boolean getMutualAuthState() 2906 Returns the state of the mutual authentication option for the 2907 context. When issued before context establishment completes or when 2908 the isProtReady method returns "false", it returns the desired state, 2909 otherwise it will indicate the actual state over the established 2910 context. 2912 GSS-API Java Bindings August 1998 2914 6.3.31. getReplayDetState 2916 public boolean getReplayDetState() 2918 Returns the state of the replay detection option for the context. 2919 When issued before context establishment completes or when the 2920 isProtReady method returns "false", it returns the desired state, 2921 otherwise it will indicate the actual state over the established 2922 context. 2924 6.3.32. getSequenceDetState 2926 public boolean getSequenceDetState() 2928 Returns the state of the sequence detection option for the context. 2929 When issued before context establishment completes or when the 2930 isProtReady method returns "false", it returns the desired state, 2931 otherwise it will indicate the actual state over the established 2932 context. 2934 6.3.33. getAnonymityState 2936 public boolean getAnonymityState() 2938 Returns "true" if this is an anonymous context. When issued before 2939 context establishment completes or when the isProtReady method 2940 returns "false", it returns the desired state, otherwise it will 2941 indicate the actual state over the established context. 2943 6.3.34. isTransferable 2945 public boolean isTransferable() throws GSSException 2947 Returns "true" if the context is transferable to other processes 2948 through the use of the export method. This call is only valid on 2949 fully established contexts. 2951 6.3.35. isProtReady 2953 public boolean isProtReady() 2955 Returns "true" if the per message operations can be applied over the 2956 context. Some mechanisms may allow the usage of per-message 2957 GSS-API Java Bindings August 1998 2959 operations before the context is fully established. This will also 2960 indicate that the get methods will return actual context state 2961 characteristics instead of the desired ones. 2963 6.3.36. getConfState 2965 public boolean getConfState() 2967 Returns the confidentiality service state over the context. When 2968 issued before context establishment completes or when the isProtReady 2969 method returns "false", it returns the desired state, otherwise it 2970 will indicate the actual state over the established context. 2972 6.3.37. getIntegState 2974 public boolean getIntegState() 2976 Returns the integrity service state over the context. When issued 2977 before context establishment completes or when the isProtReady method 2978 returns "false", it returns the desired state, otherwise it will 2979 indicate the actual state over the established context. 2981 6.3.38. getLifetime 2983 public int getLifetime() 2985 Returns the context lifetime in seconds. When issued before context 2986 establishment completes or when the isProtReady method returns 2987 "false", it returns the desired lifetime, otherwise it will indicate 2988 the remaining lifetime for the context. 2990 6.3.39. getSrcName 2992 public GSSName getSrcName() throws GSSException 2994 Returns the name of the context initiator. This call is valid only 2995 after the context is fully established or the isProtReady method 2996 returns "true". 2998 6.3.40. getTargName 3000 public GSSName getTargName() throws GSSException 3001 GSS-API Java Bindings August 1998 3003 Returns the name of the context target (acceptor). This call is 3004 valid only after the context is fully established or the isProtReady 3005 method returns "true". 3007 6.3.41. getMech 3009 public Oid getMech() throws GSSException 3011 Returns the mechanism oid for this context. 3013 6.3.42. getDelegCred 3015 public GSSCredential getDelegCred() throws GSSException 3017 Returns the delegated credential object on the acceptor's side. To 3018 check for availability of delegated credentials call 3019 getDelegCredState. This call is only valid on fully established 3020 contexts. 3022 6.3.43. isInitiator 3024 public boolean isInitiator() throws GSSException 3026 Returns "true" if this is the initiator of the context. This call is 3027 only valid after the context creation process has started. 3029 6.4. public class MessageProp 3031 This is a utility class used within the per-message GSSContext 3032 methods to convey per-message properties. 3034 When used with the GSSContext class wrap and getMIC methods, an 3035 instance of this class is used to indicate the desired QOP and to 3036 request if confidentiality services are to be applied to caller 3037 supplied data (wrap only). To request default QOP, the value of 0 3038 should be used. 3040 When used with the unwrap and verifyMIC methods of the GSSContext 3041 class, an instance of this class will be used to indicate the applied 3042 QOP and confidentiality services over the supplied message. In the 3043 case of verifyMIC, the confidentiality state will always be "false". 3044 Upon return from these methods, this object will also contain any 3045 GSS-API Java Bindings August 1998 3047 supplementary status values applicable to the processed token. The 3048 supplementary status values can indicate old tokens, out of sequence 3049 tokens, gap tokens or duplicate tokens. 3051 6.4.1. Constructors 3053 public MessageProp() 3055 Default constructor for the class. QOP is set to 0 and 3056 confidentiality to "false". 3058 public MessageProp(int qop, boolean privState) 3060 Constructor which sets the values for the qop and privacy state. 3062 Parameters: 3064 qop The desired QOP. 3066 privState The desired privacy state. 3068 6.4.2. getQOP 3070 public int getQOP() 3072 Retrieves the QOP value. 3074 6.4.3. getPrivacy 3076 public boolean getPrivacy() 3078 Retrieves the privacy state. 3080 6.4.4. setQOP 3082 public void setQOP(int qopVal) 3084 Sets the QOP value. 3086 Parameter: 3088 qopVal The QOP value to be set. 3090 GSS-API Java Bindings August 1998 3092 6.4.5. setPrivacy 3094 public void setPrivacy(boolean privState) 3096 Sets the privacy state. 3098 Parameter: 3100 privState The privacy state to set. 3102 6.4.6. isDuplicateToken 3104 public boolean isDuplicateToken() 3106 Returns "true" if this is a duplicate of an earlier token. 3108 6.4.7. isOldToken 3110 public boolean isOldToken() 3112 Returns "true" if the token's validity period has expired. 3114 6.4.8. isUnseqToken 3116 public boolean isUnseqToken() 3118 Returns "true" if a later token has already been processed. 3120 6.4.9. isGapToken 3122 public boolean isGapToken() 3124 Returns "true" if an expected per-message token was not received. 3126 6.5. public class GSSManager 3128 This class implements functionality common to the entire GSS-API 3129 package. It does not define any public constructors and all its 3130 methods are static. 3132 GSS-API Java Bindings August 1998 3134 6.5.1. getMechs 3136 public static Oid[] getMechs() 3138 Returns an array of Oid objects, one for each mechanism available 3139 within this GSS-API package. A "null" value is returned when no 3140 mechanism are available (an example of this would be when mechanism 3141 are dynamically configured, and currently no mechanisms are 3142 installed). 3144 6.5.2. getNamesForMech 3146 public static Oid[] getNamesForMech(Oid mech) throws GSSException 3148 Returns name types Oids supported by the specified mechanism. 3150 Parameters: 3152 mech The Oid object for the mechanism to query. 3154 6.5.3. getMechsForName 3156 public static Oid[] getMechsForName(Oid nameType) 3158 Returns an array of Oid objects, one for each mechanisms that support 3159 the specific name type. "null" is returned when no mechanisms are 3160 found to support the specified name type. 3162 Parameters: 3164 nameType The Oid object for the name type to query. 3166 6.5.4. getDefaultMech 3168 public static Oid getDefaultMech() 3170 Returns the default mechanism oid. This is the mechanisms that will 3171 be used when a "null" Oid object is specified in place of an Oid 3172 object within GSSCredential and GSSContext methods. 3174 6.6. public class ChannelBinding 3175 GSS-API Java Bindings August 1998 3177 The GSS-API accommodates the concept of caller-provided channel 3178 binding information. Channel bindings are used to strengthen the 3179 quality with which peer entity authentication is provided during 3180 context establishment. They enable the GSS-API callers to bind the 3181 establishment of the security context to relevant characteristics 3182 like addresses or to application specific data. 3184 The caller initiating the security context must determine the 3185 appropriate channel binding values to set in the GSSContext object. 3186 The acceptor must provide an identical binding in order to validate 3187 that received tokens possess correct channel-related characteristics. 3189 Use of channel bindings is optional in GSS-API. Since channel-binding 3190 information may be transmitted in context establishment tokens, 3191 applications should therefore not use confidential data as channel- 3192 binding components. 3194 6.6.1. Constructors 3196 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3197 byte[] appData) 3199 Create a ChannelBinding object with user supplied address information 3200 and data. "null" values can be used for any fields which the 3201 application does not want to specify. 3203 Parameters: 3205 initAddr The address of the context initiator. "null" value 3206 can be supplied to indicate that the application does 3207 not want to set this value. 3209 acceptAddrThe address of the context acceptor. "null" value can 3210 be supplied to indicate that the application does not 3211 want to set this value. 3213 appData Application supplied data to be used as part of the 3214 channel bindings. "null" value can be supplied to 3215 indicate that the application does not want to set 3216 this value. 3218 public ChannelBinding(byte[] appData) 3220 Creates a ChannelBinding object without any addressing information. 3222 Parameters: 3224 GSS-API Java Bindings August 1998 3226 appData Application supplied data to be used as part of the 3227 channel bindings. 3229 6.6.2. getInitiatorAddress 3231 public InetAddress getInitiatorAddress() 3233 Returns the initiator's address for this channel binding. "null" is 3234 returned if the address has not been set. 3236 6.6.3. getAcceptorAddress 3238 public InetAddress getAcceptorAddress() 3240 Returns the acceptor's address for this channel binding. "null" is 3241 returned if the address has not been set. 3243 6.6.4. getApplicationData 3245 public byte[] getApplicationData() 3247 Returns application data being used as part of the ChannelBinding. 3248 "null" is returned if no application data has been specified for the 3249 channel binding. 3251 6.6.5. equals 3253 public boolean equals(Object obj) 3255 Returns "true" if two channel bindings match. 3257 Parameter: 3259 obj Another channel binding to compare with. 3261 6.7. public class Oid 3263 This class represents Universal Object Identifiers (Oids) and their 3264 associated operations. 3266 Oids are hierarchically globally-interpretable identifiers used 3267 within the GSS-API framework to identify mechanisms and name formats. 3269 GSS-API Java Bindings August 1998 3271 The structure and encoding of Oids is defined in ISOIEC-8824 and 3272 ISOIEC-8825. For example the Oid representation of Kerberos V5 3273 mechanism is "1.2.840.113554.1.2.2" 3275 The GSSName name class contains public static Oid objects 3276 representing the standard name types defined in GSS-API. 3278 6.7.1. Constructors 3280 public Oid(String strOid) throws GSSException 3282 Creates an Oid object from a string representation of its integer 3283 components (e.g. "1.2.840.113554.1.2.2"). 3285 Parameters: 3287 strOid The string representation for the oid. 3289 public Oid(InputStream derOid) throws GSSException 3291 Creates an Oid object from its DER encoding. This refers to the full 3292 encoding including tag and length. The structure and encoding of 3293 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3294 identical in functionality to its byte array counterpart. 3296 Parameters: 3298 derOid Stream containing the DER encoded oid. 3300 public Oid(byte[] DEROid) throws GSSException 3302 Creates an Oid object from its DER encoding. This refers to the full 3303 encoding including tag and length. The structure and encoding of 3304 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3305 identical in functionality to its byte array counterpart. 3307 Parameters: 3309 derOid Byte array storing a DER encoded oid. 3311 6.7.2. toString 3313 public String toString() 3314 GSS-API Java Bindings August 1998 3316 Returns a string representation of the oid's integer components in 3317 dot separated notation (e.g. "1.2.840.113554.1.2.2"). 3319 6.7.3. toRFC2078String 3321 public String toRFC2078String() 3323 Returns a string representation of the Oid's integer components in 3324 the format specified within RFC 2078 (e.g. "{ 1 2 840 113554 1 2 2 3325 }"). 3327 6.7.4. equals 3329 public boolean equals(Object Obj) 3331 Returns "true" if the two Oid objects represent the same oid value. 3333 Parameter: 3335 obj Another Oid object to compare with. 3337 6.7.5. getDER 3339 public byte[] getDER() 3341 Returns the full ASN.1 DER encoding for this oid object, which 3342 includes the tag and length. 3344 6.7.6. containedIn 3346 public boolean containedIn(Oid[] oids) 3348 A utility method to test if an Oid object is contained within the 3349 supplied Oid object array. 3351 Parameter: 3353 oids An array of oids to search. 3355 6.8. public class GSSException extends Exception 3356 GSS-API Java Bindings August 1998 3358 This exception is thrown whenever a fatal GSS-API error occurs 3359 including mechanism specific errors. It may contain both, the major 3360 and minor, GSS-API status codes. The mechanism implementers are 3361 responsible for setting appropriate minor status codes when throwing 3362 this exception. Aside from delivering the numeric error code(s) to 3363 the caller, this class performs the mapping from their numeric values 3364 to textual representations. All Java GSS-API methods are declared 3365 throwing this exception. 3367 All implementations are encouraged to use the Java 3368 internationalization techniques to provide local translations of the 3369 message strings. 3371 6.8.1. Class Constants 3373 All valid major GSS-API error code values are declared as constants 3374 in this class. 3376 public static final int BAD_BINDINGS 3378 Channel bindings mismatch error. 3380 public static final int BAD_MECH 3382 Unsupported mechanism requested error. 3384 public static final int BAD_NAME 3386 Invalid name provided error. 3388 public static final int BAD_NAMETYPE 3390 Name of unsupported type provided error. 3392 public static final int BAD_STATUS 3394 Invalid status code error - this is the default status value. 3396 public static final int BAD_MIC 3398 Token had invalid integrity check error. 3400 GSS-API Java Bindings August 1998 3402 public static final int CONTEXT_EXPIRED 3404 Specified security context expired error. 3406 public static final int CREDENTIALS_EXPIRED 3408 Expired credentials detected error. 3410 public static final int DEFECTIVE_CREDENTIAL 3412 Defective credential error. 3414 public static final int DEFECTIVE_TOKEN 3416 Defective token error. 3418 public static final int FAILURE 3420 General failure, unspecified at GSS-API level. 3422 public static final int NO_CONTEXT 3424 Invalid security context error. 3426 public static final int NO_CRED 3428 Invalid credentials error. 3430 public static final int BAD_QOP 3432 Unsupported QOP value error. 3434 public static final int UNAUTHORIZED 3436 Operation unauthorized error. 3438 public static final int UNAVAILABLE 3440 Operation unavailable error. 3442 GSS-API Java Bindings August 1998 3444 public static final int DUPLICATE_ELEMENT 3446 Duplicate credential element requested error. 3448 public static final int NAME_NOT_MN 3450 Name contains multi-mechanism elements error. 3452 public static final int DUPLICATE_TOKEN 3454 The token was a duplicate of an earlier token. This is a fatal error 3455 code that may occur during context establishment. It is not used to 3456 indicate supplementary status values. The MessageProp object is used 3457 for that purpose. 3459 public static final int OLD_TOKEN 3461 The token's validity period has expired. This is a fatal error code 3462 that may occur during context establishment. It is not used to 3463 indicate supplementary status values. The MessageProp object is used 3464 for that purpose. 3466 public static final int UNSEQ_TOKEN 3468 A later token has already been processed. This is a fatal error code 3469 that may occur during context establishment. It is not used to 3470 indicate supplementary status values. The MessageProp object is used 3471 for that purpose. 3473 public static final int GAP_TOKEN 3475 An expected per-message token was not received. This is a fatal 3476 error code that may occur during context establishment. It is not 3477 used to indicate supplementary status values. The MessageProp object 3478 is used for that purpose. 3480 6.8.2. Constructors 3482 public GSSException(int majorCode) 3484 Creates a GSSException object with a specified major code. 3486 GSS-API Java Bindings August 1998 3488 Parameters: 3490 majorCode The GSS error code causing this exception to be 3491 thrown. 3493 public GSSException(int majorCode, int minorCode, String minorString) 3495 Creates a GSSException object with the specified major code, minor 3496 code, and minor code textual explanation. This constructor is to be 3497 used when the exception is originating from the security mechanism. 3498 It allows to specify the GSS code and the mechanism code. 3500 Parameters: 3502 majorCode The GSS error code causing this exception to be 3503 thrown. 3505 minorCode The mechanism error code causing this exception 3506 to be thrown. 3508 minorString The textual explanation of the mechanism error 3509 code. 3511 6.8.3. getMajor 3513 public int getMajor() 3515 Returns the major code representing the GSS error code that caused 3516 this exception to be thrown. 3518 6.8.4. getMinor 3520 public int getMinor() 3522 Returns the mechanism error code that caused this exception. The 3523 minor code is set by the underlying mechanism. Value of 0 indicates 3524 that mechanism error code is not set. 3526 6.8.5. getMajorString 3528 public String getMajorString() 3530 Returns a string explaining the GSS major error code causing this 3531 exception to be thrown. 3533 GSS-API Java Bindings August 1998 3535 6.8.6. getMinorString 3537 public String getMinorString() 3539 Returns a string explaining the mechanism specific error code. An 3540 empty string will be returned when no mechanism error code has been 3541 set. 3543 6.8.7. setMinor 3545 public void setMinor(int minorCode, String message) 3547 Used internally by the GSS-API implementation and the underlying 3548 mechanisms to set the minor code and its textual representation. 3550 Parameters: 3552 minorCode The mechanism specific error code. 3554 message A textual explanation of the mechanism error code. 3556 6.8.8. toString 3558 public String toString() 3560 Returns a textual representation of both the major and minor status 3561 codes. 3563 6.8.9. getMessage 3565 public String getMessage() 3567 Returns a detailed message of this exception. Overrides 3568 Throwable.getMessage. It is customary in Java to use this method to 3569 obtain exception information. 3571 7. Acknowledgments 3573 This proposed API leverages earlier work performed by the IETF's CAT 3574 WG as outlined in both RFC 2078 and J. Wray's C-bindings draft for 3575 the GSS-API. Many conceptual definitions, implementation directions, 3576 and explanations have been included from the C-bindings draft. 3578 GSS-API Java Bindings August 1998 3580 I would like to thank Mike Eisler, Mayank Upadhyay, Lin Ling, Ram 3581 Marti, Michael Saltz and other members of Sun's development team for 3582 their helpful input, comments and suggestions. 3584 I would also like to thank Michael Smith for many insightful ideas 3585 and suggestions that have contributed to this draft. 3587 GSS-API Java Bindings August 1998 3589 8. Bibliography 3591 [GSSAPIv2] 3592 J. Linn, "Generic Security Service Application Program Interface, 3593 Version 2", RFC 2078, January 1997. 3595 [GSSAPIv2-UPDATE] 3596 J. Linn, "Generic Security Service Application Program Interface, 3597 Version 2, Update 1", IETF work in progress, Internet Draft, July 3598 1998. 3600 [GSSAPI-Cbind] 3601 J. Wray, "Generic Security Service API Version 2 : C-bindings", IETF 3602 work in progress, Internet Draft, July 1998. 3604 [KERBEROS_V5] 3605 J. Linn, "The Kerberos Version 5 GSS-API Mechanism", RFC 1964, June 3606 1996. 3608 [SPKM] 3609 C. Adams, "The Simple Public-Key GSS-API Mechanism", RFC 2025, 3610 October 1996. 3612 GSS-API Java Bindings August 1998 3614 9. Author's Address 3616 Address comments related to this memorandum to: 3618 3620 Jack Kabat 3621 Sun Microsystems, Inc. 3622 17 Network Circle, MPK 017 3623 Menlo Park, CA 3624 94025, USA 3626 Phone: +1-650-786-5072 3627 E-mail: jkabat@eng.sun.com