idnits 2.17.1 draft-ietf-kitten-rfc5653bis-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- == There are 4 instances of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 12, 2017) is 2357 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2853 (Obsoleted by RFC 5653) ** Obsolete normative reference: RFC 5653 (Obsoleted by RFC 8353) Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Upadhyay 3 Internet-Draft Google 4 Obsoletes: 5653 (if approved) S. Malkani 5 Intended status: Standards Track ActivIdentity 6 Expires: May 16, 2018 W. Wang 7 Oracle 8 November 12, 2017 10 Generic Security Service API Version 2: Java Bindings Update 11 draft-ietf-kitten-rfc5653bis-06 13 Abstract 15 The Generic Security Services Application Program Interface (GSS-API) 16 offers application programmers uniform access to security services 17 atop a variety of underlying cryptographic mechanisms. This document 18 updates the Java bindings for the GSS-API that are specified in 19 "Generic Security Service API Version 2 : Java Bindings Update" (RFC 20 5653). This document obsoletes RFC 5653 by adding a new output token 21 field to the GSSException class so that when the initSecContext or 22 acceptSecContext methods of the GSSContext class fails it has a 23 chance to emit an error token which can be sent to the peer for 24 debugging or informational purpose. The stream-based GSSContext 25 methods are also removed in this version. 27 The GSS-API is described at a language-independent conceptual level 28 in "Generic Security Service Application Program Interface Version 2, 29 Update 1" (RFC 2743). The GSS-API allows a caller application to 30 authenticate a principal identity, to delegate rights to a peer, and 31 to apply security services such as confidentiality and integrity on a 32 per-message basis. Examples of security mechanisms defined for GSS- 33 API are "The Simple Public-Key GSS-API Mechanism" (RFC 2025) and "The 34 Kerberos Version 5 Generic Security Service Application Program 35 Interface (GSS-API) Mechanism: Version 2" (RFC 4121). 37 Status of This Memo 39 This Internet-Draft is submitted in full conformance with the 40 provisions of BCP 78 and BCP 79. 42 Internet-Drafts are working documents of the Internet Engineering 43 Task Force (IETF). Note that other groups may also distribute 44 working documents as Internet-Drafts. The list of current Internet- 45 Drafts is at https://datatracker.ietf.org/drafts/current/. 47 Internet-Drafts are draft documents valid for a maximum of six months 48 and may be updated, replaced, or obsoleted by other documents at any 49 time. It is inappropriate to use Internet-Drafts as reference 50 material or to cite them other than as "work in progress." 52 This Internet-Draft will expire on May 16, 2018. 54 Copyright Notice 56 Copyright (c) 2017 IETF Trust and the persons identified as the 57 document authors. All rights reserved. 59 This document is subject to BCP 78 and the IETF Trust's Legal 60 Provisions Relating to IETF Documents 61 (https://trustee.ietf.org/license-info) in effect on the date of 62 publication of this document. Please review these documents 63 carefully, as they describe your rights and restrictions with respect 64 to this document. Code Components extracted from this document must 65 include Simplified BSD License text as described in Section 4.e of 66 the Trust Legal Provisions and are provided without warranty as 67 described in the Simplified BSD License. 69 This document may contain material from IETF Documents or IETF 70 Contributions published or made publicly available before November 71 10, 2008. The person(s) controlling the copyright in some of this 72 material may not have granted the IETF Trust the right to allow 73 modifications of such material outside the IETF Standards Process. 74 Without obtaining an adequate license from the person(s) controlling 75 the copyright in such materials, this document may not be modified 76 outside the IETF Standards Process, and derivative works of it may 77 not be created outside the IETF Standards Process, except to format 78 it for publication as an RFC or to translate it into languages other 79 than English. 81 Table of Contents 83 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 84 2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 7 85 3. Additional Controls . . . . . . . . . . . . . . . . . . . . . 8 86 3.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . 9 87 3.2. Mutual Authentication . . . . . . . . . . . . . . . . . . 10 88 3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 11 89 3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 11 90 3.5. Integrity and Confidentiality . . . . . . . . . . . . . . 12 91 3.6. Inter-process Context Transfer . . . . . . . . . . . . . 13 92 3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 13 93 4. Calling Conventions . . . . . . . . . . . . . . . . . . . . . 14 94 4.1. Package Name . . . . . . . . . . . . . . . . . . . . . . 14 95 4.2. Provider Framework . . . . . . . . . . . . . . . . . . . 14 96 4.3. Integer Types . . . . . . . . . . . . . . . . . . . . . . 15 97 4.4. Opaque Data Types . . . . . . . . . . . . . . . . . . . . 15 98 4.5. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 15 99 4.6. Object Identifiers . . . . . . . . . . . . . . . . . . . 16 100 4.7. Object Identifier Sets . . . . . . . . . . . . . . . . . 16 101 4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . . 16 102 4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18 103 4.10. Authentication Tokens . . . . . . . . . . . . . . . . . . 19 104 4.11. Inter-Process Tokens . . . . . . . . . . . . . . . . . . 19 105 4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . . 19 106 4.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . 20 107 4.12.2. Mechanism-Specific Status Codes . . . . . . . . . . 22 108 4.12.3. Supplementary Status Codes . . . . . . . . . . . . . 22 109 4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 23 110 4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . . 26 111 4.15. Optional Parameters . . . . . . . . . . . . . . . . . . . 27 112 5. Introduction to GSS-API Classes and Interfaces . . . . . . . 27 113 5.1. GSSManager Class . . . . . . . . . . . . . . . . . . . . 27 114 5.2. GSSName Interface . . . . . . . . . . . . . . . . . . . . 28 115 5.3. GSSCredential Interface . . . . . . . . . . . . . . . . . 29 116 5.4. GSSContext Interface . . . . . . . . . . . . . . . . . . 30 117 5.5. MessageProp Class . . . . . . . . . . . . . . . . . . . . 32 118 5.6. GSSException Class . . . . . . . . . . . . . . . . . . . 32 119 5.7. Oid Class . . . . . . . . . . . . . . . . . . . . . . . . 32 120 5.8. ChannelBinding Class . . . . . . . . . . . . . . . . . . 32 121 6. Detailed GSS-API Class Description . . . . . . . . . . . . . 33 122 6.1. public abstract class GSSManager . . . . . . . . . . . . 33 123 6.1.1. getInstance . . . . . . . . . . . . . . . . . . . . . 34 124 6.1.2. getMechs . . . . . . . . . . . . . . . . . . . . . . 34 125 6.1.3. getNamesForMech . . . . . . . . . . . . . . . . . . . 34 126 6.1.4. getMechsForName . . . . . . . . . . . . . . . . . . . 35 127 6.1.5. createName . . . . . . . . . . . . . . . . . . . . . 35 128 6.1.6. createName . . . . . . . . . . . . . . . . . . . . . 35 129 6.1.7. createName . . . . . . . . . . . . . . . . . . . . . 36 130 6.1.8. createName . . . . . . . . . . . . . . . . . . . . . 37 131 6.1.9. createCredential . . . . . . . . . . . . . . . . . . 37 132 6.1.10. createCredential . . . . . . . . . . . . . . . . . . 38 133 6.1.11. createCredential . . . . . . . . . . . . . . . . . . 38 134 6.1.12. createContext . . . . . . . . . . . . . . . . . . . . 39 135 6.1.13. createContext . . . . . . . . . . . . . . . . . . . . 40 136 6.1.14. createContext . . . . . . . . . . . . . . . . . . . . 40 137 6.1.15. addProviderAtFront . . . . . . . . . . . . . . . . . 40 138 6.1.15.1. addProviderAtFront Example Code . . . . . . . . 41 139 6.1.16. addProviderAtEnd . . . . . . . . . . . . . . . . . . 42 140 6.1.16.1. addProviderAtEnd Example Code . . . . . . . . . 43 141 6.1.17. Example Code . . . . . . . . . . . . . . . . . . . . 44 142 6.2. public interface GSSName . . . . . . . . . . . . . . . . 44 143 6.2.1. Static Constants . . . . . . . . . . . . . . . . . . 44 144 6.2.2. equals . . . . . . . . . . . . . . . . . . . . . . . 45 145 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . 45 146 6.2.4. canonicalize . . . . . . . . . . . . . . . . . . . . 46 147 6.2.5. export . . . . . . . . . . . . . . . . . . . . . . . 46 148 6.2.6. toString . . . . . . . . . . . . . . . . . . . . . . 46 149 6.2.7. getStringNameType . . . . . . . . . . . . . . . . . . 47 150 6.2.8. isAnonymous . . . . . . . . . . . . . . . . . . . . . 47 151 6.2.9. isMN . . . . . . . . . . . . . . . . . . . . . . . . 47 152 6.2.10. Example Code . . . . . . . . . . . . . . . . . . . . 47 153 6.3. public interface GSSCredential implements Cloneable . . . 48 154 6.3.1. Static Constants . . . . . . . . . . . . . . . . . . 49 155 6.3.2. dispose . . . . . . . . . . . . . . . . . . . . . . . 50 156 6.3.3. getName . . . . . . . . . . . . . . . . . . . . . . . 50 157 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 50 158 6.3.5. getRemainingLifetime . . . . . . . . . . . . . . . . 50 159 6.3.6. getRemainingInitLifetime . . . . . . . . . . . . . . 51 160 6.3.7. getRemainingAcceptLifetime . . . . . . . . . . . . . 51 161 6.3.8. getUsage . . . . . . . . . . . . . . . . . . . . . . 51 162 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 163 6.3.10. getMechs . . . . . . . . . . . . . . . . . . . . . . 52 164 6.3.11. add . . . . . . . . . . . . . . . . . . . . . . . . . 52 165 6.3.12. equals . . . . . . . . . . . . . . . . . . . . . . . 53 166 6.3.13. Example Code . . . . . . . . . . . . . . . . . . . . 53 167 6.4. public interface GSSContext . . . . . . . . . . . . . . . 54 168 6.4.1. Static Constants . . . . . . . . . . . . . . . . . . 55 169 6.4.2. initSecContext . . . . . . . . . . . . . . . . . . . 55 170 6.4.3. acceptSecContext . . . . . . . . . . . . . . . . . . 56 171 6.4.4. isEstablished . . . . . . . . . . . . . . . . . . . . 57 172 6.4.5. dispose . . . . . . . . . . . . . . . . . . . . . . . 57 173 6.4.6. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 57 174 6.4.7. wrap . . . . . . . . . . . . . . . . . . . . . . . . 58 175 6.4.8. unwrap . . . . . . . . . . . . . . . . . . . . . . . 59 176 6.4.9. getMIC . . . . . . . . . . . . . . . . . . . . . . . 60 177 6.4.10. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 60 178 6.4.11. export . . . . . . . . . . . . . . . . . . . . . . . 61 179 6.4.12. requestMutualAuth . . . . . . . . . . . . . . . . . . 62 180 6.4.13. requestReplayDet . . . . . . . . . . . . . . . . . . 62 181 6.4.14. requestSequenceDet . . . . . . . . . . . . . . . . . 62 182 6.4.15. requestCredDeleg . . . . . . . . . . . . . . . . . . 63 183 6.4.16. requestAnonymity . . . . . . . . . . . . . . . . . . 63 184 6.4.17. requestConf . . . . . . . . . . . . . . . . . . . . . 63 185 6.4.18. requestInteg . . . . . . . . . . . . . . . . . . . . 64 186 6.4.19. requestLifetime . . . . . . . . . . . . . . . . . . . 64 187 6.4.20. setChannelBinding . . . . . . . . . . . . . . . . . . 64 188 6.4.21. getCredDelegState . . . . . . . . . . . . . . . . . . 64 189 6.4.22. getMutualAuthState . . . . . . . . . . . . . . . . . 65 190 6.4.23. getReplayDetState . . . . . . . . . . . . . . . . . . 65 191 6.4.24. getSequenceDetState . . . . . . . . . . . . . . . . . 65 192 6.4.25. getAnonymityState . . . . . . . . . . . . . . . . . . 65 193 6.4.26. isTransferable . . . . . . . . . . . . . . . . . . . 65 194 6.4.27. isProtReady . . . . . . . . . . . . . . . . . . . . . 66 195 6.4.28. getConfState . . . . . . . . . . . . . . . . . . . . 66 196 6.4.29. getIntegState . . . . . . . . . . . . . . . . . . . . 66 197 6.4.30. getLifetime . . . . . . . . . . . . . . . . . . . . . 66 198 6.4.31. getSrcName . . . . . . . . . . . . . . . . . . . . . 66 199 6.4.32. getTargName . . . . . . . . . . . . . . . . . . . . . 67 200 6.4.33. getMech . . . . . . . . . . . . . . . . . . . . . . . 67 201 6.4.34. getDelegCred . . . . . . . . . . . . . . . . . . . . 67 202 6.4.35. isInitiator . . . . . . . . . . . . . . . . . . . . . 67 203 6.4.36. Example Code . . . . . . . . . . . . . . . . . . . . 67 204 6.5. public class MessageProp . . . . . . . . . . . . . . . . 69 205 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 70 206 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 70 207 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 70 208 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 70 209 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 70 210 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 71 211 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 71 212 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 71 213 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 71 214 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 71 215 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 71 216 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 72 217 6.6. public class ChannelBinding . . . . . . . . . . . . . . . 72 218 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 73 219 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 73 220 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 73 221 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . 74 222 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 74 223 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 74 224 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 74 225 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 75 226 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 75 227 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 76 228 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 76 229 6.8. public class GSSException extends Exception . . . . . . . 76 230 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . 76 231 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 79 232 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 80 233 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 80 234 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 80 235 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 80 236 6.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 81 237 6.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 81 238 6.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 81 239 6.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 81 240 7. Sample Applications . . . . . . . . . . . . . . . . . . . . . 81 241 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 82 242 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 85 243 8. Security Considerations . . . . . . . . . . . . . . . . . . . 89 244 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 90 245 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 90 246 11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 90 247 12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 92 248 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 92 249 13.1. Normative References . . . . . . . . . . . . . . . . . . 92 250 13.2. Informative References . . . . . . . . . . . . . . . . . 93 251 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 93 253 1. Introduction 255 This document specifies Java language bindings for the Generic 256 Security Services Application Programming Interface version 2 (GSS- 257 API). GSS-API version 2 is described in a language-independent 258 format in RFC 2743 [RFC2743]. The GSS-API allows a caller 259 application to authenticate a principal identity, to delegate rights 260 to a peer, and to apply security services such as confidentiality and 261 integrity on a per-message basis. 263 This document and its predecessor, RFC 2853 [RFC2853] and RFC 5653 264 [RFC5653], leverage the work done by the working group (WG) in the 265 area of RFC 2743 [RFC2743] and the C-bindings of RFC 2744 [RFC2744]. 266 Whenever appropriate, text has been used from the C-bindings document 267 (RFC 2744) to explain generic concepts and provide direction to the 268 implementors. 270 The design goals of this API have been to satisfy all the 271 functionality defined in RFC 2743 [RFC2743] and to provide these 272 services in an object-oriented method. The specification also aims 273 to satisfy the needs of both types of Java application developers, 274 those who would like access to a "system-wide" GSS-API 275 implementation, as well as those who would want to provide their own 276 "custom" implementation. 278 A system-wide implementation is one that is available to all 279 applications in the form of a library package. It may be the 280 standard package in the Java runtime environment (JRE) being used or 281 it may be additionally installed and accessible to any application 282 via the CLASSPATH. 284 A custom implementation of the GSS-API, on the other hand, is one 285 that would, in most cases, be bundled with the application during 286 distribution. It is expected that such an implementation would be 287 meant to provide for some particular need of the application, such as 288 support for some specific mechanism. 290 The design of this API also aims to provide a flexible framework to 291 add and manage GSS-API mechanisms. GSS-API leverages the Java 292 Cryptography Architecture (JCA) provider model to support the 293 plugability of mechanisms. Mechanisms can be added on a system-wide 294 basis, where all users of the framework will have them available. 295 The specification also allows for the addition of mechanisms per- 296 instance of the GSS-API. 298 Lastly, this specification presents an API that will naturally fit 299 within the operation environment of the Java platform. Readers are 300 assumed to be familiar with both the GSS-API and the Java platform. 302 2. GSS-API Operational Paradigm 304 "Generic Security Service Application Programming Interface, Version 305 2" [RFC2743] defines a generic security API to calling applications. 306 It allows a communicating application to authenticate the user 307 associated with another application, to delegate rights to another 308 application, and to apply security services such as confidentiality 309 and integrity on a per-message basis. 311 There are four stages to using GSS-API: 313 1) The application acquires a set of credentials with which it may 314 prove its identity to other processes. The application's 315 credentials vouch for its global identity, which may or may not be 316 related to any local username under which it may be running. 318 2) A pair of communicating applications establish a joint security 319 context using their credentials. The security context 320 encapsulates shared state information, which is required in order 321 that per-message security services may be provided. Examples of 322 state information that might be shared between applications as 323 part of a security context are cryptographic keys and message 324 sequence numbers. As part of the establishment of a security 325 context, the context initiator is authenticated to the responder, 326 and may require that the responder is authenticated back to the 327 initiator. The initiator may optionally give the responder the 328 right to initiate further security contexts, acting as an agent or 329 delegate of the initiator. This transfer of rights is termed 330 "delegation", and is achieved by creating a set of credentials, 331 similar to those used by the initiating application, but which may 332 be used by the responder. 334 A GSSContext object is used to establish and maintain the shared 335 information that makes up the security context. Certain 336 GSSContext methods will generate a token, which applications treat 337 as cryptographically protected, opaque data. The caller of such a 338 GSSContext method is responsible for transferring the token to the 339 peer application, encapsulated if necessary in an application-to- 340 application protocol. On receipt of such a token, the peer 341 application should pass it to a corresponding GSSContext method 342 which will decode the token and extract the information, updating 343 the security context state information accordingly. 345 3) Per-message services are invoked on a GSSContext object to apply 346 either: 348 integrity and data origin authentication, or 350 confidentiality, integrity and data origin authentication 352 to application data, which are treated by GSS-API as arbitrary 353 octet-strings. An application transmitting a message that it 354 wishes to protect will call the appropriate GSSContext method 355 (getMIC or wrap) to apply protection, and send the resulting token 356 to the receiving application. The receiver will pass the received 357 token (and, in the case of data protected by getMIC, the 358 accompanying message-data) to the corresponding decoding method of 359 the GSSContext interface (verifyMIC or unwrap) to remove the 360 protection and validate the data. 362 4) At the completion of a communications session (which may extend 363 across several transport connections), each application uses a 364 GSSContext method to invalidate the security context and release 365 any system or cryptographic resources held. Multiple contexts may 366 also be used (either successively or simultaneously) within a 367 single communications association, at the discretion of the 368 applications. 370 3. Additional Controls 372 This section discusses the optional services that a context initiator 373 may request of the GSS-API before the context establishment. Each of 374 these services is requested by calling the appropriate mutator method 375 in the GSSContext object before the first call to init is performed. 376 Only the context initiator can request context flags. 378 The optional services defined are: 380 Delegation: The (usually temporary) transfer of rights from 381 initiator to acceptor, enabling the acceptor to authenticate 382 itself as an agent of the initiator. 384 Mutual Authentication: In addition to the initiator authenticating 385 its identity to the context acceptor, the context acceptor should 386 also authenticate itself to the initiator. 388 Replay Detection: In addition to providing message integrity 389 services, GSSContext per-message operations of getMIC and wrap 390 should include message numbering information to enable verifyMIC 391 and unwrap to detect if a message has been duplicated. 393 Out-of-Sequence Detection: In addition to providing message 394 integrity services, GSSContext per-message operations (getMIC and 395 wrap) should include message sequencing information to enable 396 verifyMIC and unwrap to detect if a message has been received out 397 of sequence. 399 Anonymous Authentication: The establishment of the security 400 context should not reveal the initiator's identity to the context 401 acceptor. 403 Some mechanisms may not support all optional services, and some 404 mechanisms may only support some services in conjunction with others. 405 The GSSContext interface offers query methods to allow the 406 verification by the calling application of which services will be 407 available from the context when the establishment phase is complete. 408 In general, if the security mechanism is capable of providing a 409 requested service, it should do so even if additional services must 410 be enabled in order to provide the requested service. If the 411 mechanism is incapable of providing a requested service, it should 412 proceed without the service leaving the application to abort the 413 context establishment process if it considers the requested service 414 to be mandatory. 416 Some mechanisms may specify that support for some services is 417 optional, and that implementors of the mechanism need not provide it. 418 This is most commonly true of the confidentiality service, often 419 because of legal restrictions on the use of data-encryption, but may 420 apply to any of the services. Such mechanisms are required to send 421 at least one token from acceptor to initiator during context 422 establishment when the initiator indicates a desire to use such a 423 service, so that the initiating GSS-API can correctly indicate 424 whether the service is supported by the acceptor's GSS-API. 426 3.1. Delegation 428 The GSS-API allows delegation to be controlled by the initiating 429 application via the requestCredDeleg method before the first call to 430 init has been issued. Some mechanisms do not support delegation, and 431 for such mechanisms, attempts by an application to enable delegation 432 are ignored. 434 The acceptor of a security context, for which the initiator enabled 435 delegation, can check if delegation was enabled by using the 436 getCredDelegState method of the GSSContext interface. In cases when 437 it is enabled, the delegated credential object can be obtained by 438 calling the getDelegCred method. The obtained GSSCredential object 439 may then be used to initiate subsequent GSS-API security contexts as 440 an agent or delegate of the initiator. If the original initiator's 441 identity is "A" and the delegate's identity is "B", then, depending 442 on the underlying mechanism, the identity embodied by the delegated 443 credential may be either "A" or "B acting for A". 445 For many mechanisms that support delegation, a simple boolean does 446 not provide enough control. Examples of additional aspects of 447 delegation control that a mechanism might provide to an application 448 are duration of delegation, network addresses from which delegation 449 is valid, and constraints on the tasks that may be performed by a 450 delegate. Such controls are presently outside the scope of the GSS- 451 API. GSS-API implementations supporting mechanisms offering 452 additional controls should provide extension routines that allow 453 these controls to be exercised (perhaps by modifying the initiator's 454 GSS-API credential object prior to its use in establishing a 455 context). However, the simple delegation control provided by GSS-API 456 should always be able to override other mechanism-specific delegation 457 controls. If the application instructs the GSSContext object that 458 delegation is not desired, then the implementation must not permit 459 delegation to occur. This is an exception to the general rule that a 460 mechanism may enable services even if they are not requested -- 461 delegation may only be provided at the explicit request of the 462 application. 464 3.2. Mutual Authentication 466 Usually, a context acceptor will require that a context initiator 467 authenticate itself so that the acceptor may make an access-control 468 decision prior to performing a service for the initiator. In some 469 cases, the initiator may also request that the acceptor authenticate 470 itself. GSS-API allows the initiating application to request this 471 mutual authentication service by calling the requestMutualAuth method 472 of the GSSContext interface with a "true" parameter before making the 473 first call to init. The initiating application is informed as to 474 whether or not the context acceptor has authenticated itself. Note 475 that some mechanisms may not support mutual authentication, and other 476 mechanisms may always perform mutual authentication, whether or not 477 the initiating application requests it. In particular, mutual 478 authentication may be required by some mechanisms in order to support 479 replay or out-of-sequence message detection, and for such mechanisms, 480 a request for either of these services will automatically enable 481 mutual authentication. 483 3.3. Replay and Out-of-Sequence Detection 485 The GSS-API may provide detection of mis-ordered messages once a 486 security context has been established. Protection may be applied to 487 messages by either application, by calling either getMIC or wrap 488 methods of the GSSContext interface, and verified by the peer 489 application by calling verifyMIC or unwrap for the peer's GSSContext 490 object. 492 The getMIC method calculates a cryptographic checksum (authentication 493 tag) of an application message, and returns that checksum in a token. 494 The application should pass both the token and the message to the 495 peer application, which presents them to the verifyMIC method of the 496 peer's GSSContext object. 498 The wrap method calculates a cryptographic checksum of an application 499 message, and places both the checksum and the message inside a single 500 token. The application should pass the token to the peer 501 application, which presents it to the unwrap method of the peer's 502 GSSContext object to extract the message and verify the checksum. 504 Either pair of routines may be capable of detecting out-of-sequence 505 message delivery or the duplication of messages. Details of such 506 mis-ordered messages are indicated through supplementary query 507 methods of the MessageProp object that is filled in by each of these 508 routines. 510 A mechanism need not maintain a list of all tokens that have been 511 processed in order to support these status codes. A typical 512 mechanism might retain information about only the most recent "N" 513 tokens processed, allowing it to distinguish duplicates and missing 514 tokens within the most recent "N" messages; the receipt of a token 515 older than the most recent "N" would result in the isOldToken method 516 of the instance of MessageProp to return "true". 518 3.4. Anonymous Authentication 520 In certain situations, an application may wish to initiate the 521 authentication process to authenticate a peer, without revealing its 522 own identity. As an example, consider an application providing 523 access to a database containing medical information and offering 524 unrestricted access to the service. A client of such a service might 525 wish to authenticate the service (in order to establish trust in any 526 information retrieved from it), but might not wish the service to be 527 able to obtain the client's identity (perhaps due to privacy concerns 528 about the specific inquiries, or perhaps simply to avoid being placed 529 on mailing-lists). 531 In normal use of the GSS-API, the initiator's identity is made 532 available to the acceptor as a result of the context establishment 533 process. However, context initiators may request that their identity 534 not be revealed to the context acceptor. Many mechanisms do not 535 support anonymous authentication, and for such mechanisms, the 536 request will not be honored. An authentication token will still be 537 generated, but the application is always informed if a requested 538 service is unavailable, and has the option to abort context 539 establishment if anonymity is valued above the other security 540 services that would require a context to be established. 542 In addition to informing the application that a context is 543 established anonymously (via the isAnonymous method of the GSSContext 544 class), the getSrcName method of the acceptor's GSSContext object 545 will, for such contexts, return a reserved internal-form name, 546 defined by the implementation. 548 The toString method for a GSSName object representing an anonymous 549 entity will return a printable name. The returned value will be 550 syntactically distinguishable from any valid principal name supported 551 by the implementation. The associated name-type object identifier 552 will be an oid representing the value of NT_ANONYMOUS. This name- 553 type oid will be defined as a public, static Oid object of the 554 GSSName class. The printable form of an anonymous name should be 555 chosen such that it implies anonymity, since this name may appear in, 556 for example, audit logs. For example, the string "" might 557 be a good choice, if no valid printable names supported by the 558 implementation can begin with "<" and end with ">". 560 When using the equal method of the GSSName interface, and one of the 561 operands is a GSSName instance representing an anonymous entity, the 562 method must return "false". 564 3.5. Integrity and Confidentiality 566 If a GSSContext supports the integrity service, getMic method may be 567 used to create message integrity check tokens on application 568 messages. 570 If a GSSContext supports the confidentiality service, wrap method may 571 be used to encrypt application messages. Messages are selectively 572 encrypted, under the control of the setPrivacy method of the 573 MessageProp object used in the wrap method. Confidentiality will be 574 applied if the privacy state is set to true. 576 3.6. Inter-process Context Transfer 578 GSS-APIv2 provides functionality that allows a security context to be 579 transferred between processes on a single machine. These are 580 implemented using the export method of GSSContext and a byte array 581 constructor of the same class. The most common use for such a 582 feature is a client-server design where the server is implemented as 583 a single process that accepts incoming security contexts, which then 584 launches child processes to deal with the data on these contexts. In 585 such a design, the child processes must have access to the security 586 context object created within the parent so that they can use per- 587 message protection services and delete the security context when the 588 communication session ends. 590 Since the security context data structure is expected to contain 591 sequencing information, it is impractical in general to share a 592 context between processes. Thus, the GSSContext interface provides 593 an export method that the process, which currently owns the context, 594 can call to declare that it has no intention to use the context 595 subsequently, and to create an inter-process token containing 596 information needed by the adopting process to successfully recreate 597 the context. After successful completion of export, the original 598 security context is made inaccessible to the calling process by GSS- 599 API, and any further usage of this object will result in failures. 600 The originating process transfers the inter-process token to the 601 adopting process, which creates a new GSSContext object using the 602 byte array constructor. The properties of the context are equivalent 603 to that of the original context. 605 The inter-process token may contain sensitive data from the original 606 security context (including cryptographic keys). Applications using 607 inter-process tokens to transfer security contexts must take 608 appropriate steps to protect these tokens in transit. 610 Implementations are not required to support the inter-process 611 transfer of security contexts. Calling the isTransferable method of 612 the GSSContext interface will indicate if the context object is 613 transferable. 615 3.7. The Use of Incomplete Contexts 617 Some mechanisms may allow the per-message services to be used before 618 the context establishment process is complete. For example, a 619 mechanism may include sufficient information in its initial context- 620 level tokens for the context acceptor to immediately decode messages 621 protected with wrap or getMIC. For such a mechanism, the initiating 622 application need not wait until subsequent context-level tokens have 623 been sent and received before invoking the per-message protection 624 services. 626 An application can invoke the isProtReady method of the GSSContext 627 class to determine if the per-message services are available in 628 advance of complete context establishment. Applications wishing to 629 use per-message protection services on partially established contexts 630 should query this method before attempting to invoke wrap or getMIC. 632 4. Calling Conventions 634 Java provides the implementors with not just a syntax for the 635 language, but also an operational environment. For example, memory 636 is automatically managed and does not require application 637 intervention. These language features have allowed for a simpler API 638 and have led to the elimination of certain GSS-API functions. 640 Moreover, the JCA defines a provider model that allows for 641 implementation-independent access to security services. Using this 642 model, applications can seamlessly switch between different 643 implementations and dynamically add new services. The GSS-API 644 specification leverages these concepts by the usage of providers for 645 the mechanism implementations. 647 4.1. Package Name 649 The classes and interfaces defined in this document reside in the 650 package called "org.ietf.jgss". Applications that wish to make use 651 of this API should import this package name as shown in section 7. 653 4.2. Provider Framework 655 The Java security API's use a provider architecture that allows 656 applications to be implementation independent and security API 657 implementations to be modular and extensible. The 658 java.security.Provider class is an abstract class that a vendor 659 extends. This class maps various properties that represent different 660 security services that are available to the names of the actual 661 vendor classes that implement those services. When requesting a 662 service, an application simply specifies the desired provider and the 663 API delegates the request to service classes available from that 664 provider. 666 Using the Java security provider model insulates applications from 667 implementation details of the services they wish to use. 668 Applications can switch between providers easily and new providers 669 can be added as needed, even at runtime. 671 The GSS-API may use providers to find components for specific 672 underlying security mechanisms. For instance, a particular provider 673 might contain components that will allow the GSS-API to support the 674 Kerberos v5 mechanism [RFC4121] and another might contain components 675 to support the Simple Public-Key GSS-API Mechanism (SPKM) [RFC2025]. 676 By delegating mechanism-specific functionality to the components 677 obtained from providers, the GSS-API can be extended to support an 678 arbitrary list of mechanism. 680 How the GSS-API locates and queries these providers is beyond the 681 scope of this document and is being deferred to a Service Provider 682 Interface (SPI) specification. The availability of such an SPI 683 specification is not mandatory for the adoption of this API 684 specification nor is it mandatory to use providers in the 685 implementation of a GSS-API framework. However, by using the 686 provider framework together with an SPI specification, one can create 687 an extensible and implementation-independent GSS-API framework. 689 4.3. Integer Types 691 All numeric values are declared as "int" primitive Java type. The 692 Java specification guarantees that this will be a 32-bit two's 693 complement signed number. 695 Throughout this API, the "boolean" primitive Java type is used 696 wherever a boolean value is required or returned. 698 4.4. Opaque Data Types 700 Java byte arrays are used to represent opaque data types that are 701 consumed and produced by the GSS-API in the form of tokens. Java 702 arrays contain a length field that enables the users to easily 703 determine their size. The language has automatic garbage collection 704 that alleviates the need by developers to release memory and 705 simplifies buffer ownership issues. 707 4.5. Strings 709 The String object will be used to represent all textual data. The 710 Java String object transparently treats all characters as two-byte 711 Unicode characters, which allows support for many locals. All 712 routines returning or accepting textual data will use the String 713 object. 715 4.6. Object Identifiers 717 An Oid object will be used to represent Universal Object Identifiers 718 (Oids). Oids are ISO-defined, hierarchically globally interpretable 719 identifiers used within the GSS-API framework to identify security 720 mechanisms and name formats. The Oid object can be created from a 721 string representation of its dot notation (e.g., "1.3.6.1.5.6.2") as 722 well as from its ASN.1 DER encoding. Methods are also provided to 723 test equality and provide the DER representation for the object. 725 An important feature of the Oid class is that its instances are 726 immutable -- i.e., there are no methods defined that allow one to 727 change the contents of an Oid. This property allows one to treat 728 these objects as "statics" without the need to perform copies. 730 Certain routines allow the usage of a default oid. A "null" value 731 can be used in those cases. 733 4.7. Object Identifier Sets 735 The Java bindings represent object identifier sets as arrays of Oid 736 objects. All Java arrays contain a length field, which allows for 737 easy manipulation and reference. 739 In order to support the full functionality of RFC 2743 [RFC2743], the 740 Oid class includes a method that checks for existence of an Oid 741 object within a specified array. This is equivalent in functionality 742 to gss_test_oid_set_member. The use of Java arrays and Java's 743 automatic garbage collection has eliminated the need for the 744 following routines: gss_create_empty_oid_set, gss_release_oid_set, 745 and gss_add_oid_set_member. Java GSS-API implementations will not 746 contain them. Java's automatic garbage collection and the immutable 747 property of the Oid object eliminates the memory management issues of 748 the C counterpart. 750 Whenever a default value for an Object Identifier Set is required, a 751 "null" value can be used. Please consult the detailed method 752 description for details. 754 4.8. Credentials 756 GSS-API credentials are represented by the GSSCredential interface. 757 The interface contains several constructs to allow for the creation 758 of most common credential objects for the initiator and the acceptor. 759 Comparisons are performed using the interface's "equals" method. The 760 following general description of GSS-API credentials is included from 761 the C-bindings specification: 763 GSS-API credentials can contain mechanism-specific principal 764 authentication data for multiple mechanisms. A GSS-API credential 765 is composed of a set of credential-elements, each of which is 766 applicable to a single mechanism. A credential may contain at 767 most one credential-element for each supported mechanism. A 768 credential-element identifies the data needed by a single 769 mechanism to authenticate a single principal, and conceptually 770 contains two credential-references that describe the actual 771 mechanism-specific authentication data, one to be used by GSS-API 772 for initiating contexts, and one to be used for accepting 773 contexts. For mechanisms that do not distinguish between acceptor 774 and initiator credentials, both references would point to the same 775 underlying mechanism-specific authentication data. 777 Credentials describe a set of mechanism-specific principals, and give 778 their holder the ability to act as any of those principals. All 779 principal identities asserted by a single GSS-API credential should 780 belong to the same entity, although enforcement of this property is 781 an implementation-specific matter. A single GSSCredential object 782 represents all the credential elements that have been acquired. 784 The creation of an GSSContext object allows the value of "null" to be 785 specified as the GSSCredential input parameter. This will indicate a 786 desire by the application to act as a default principal. While 787 individual GSS-API implementations are free to determine such default 788 behavior as appropriate to the mechanism, the following default 789 behavior by these routines is recommended for portability: 791 For the initiator side of the context: 793 1) If there is only a single principal capable of initiating security 794 contexts for the chosen mechanism that the application is 795 authorized to act on behalf of, then that principal shall be used; 796 otherwise, 798 2) If the platform maintains a concept of a default network-identity 799 for the chosen mechanism, and if the application is authorized to 800 act on behalf of that identity for the purpose of initiating 801 security contexts, then the principal corresponding to that 802 identity shall be used; otherwise, 804 3) If the platform maintains a concept of a default local identity, 805 and provides a means to map local identities into network- 806 identities for the chosen mechanism, and if the application is 807 authorized to act on behalf of the network-identity image of the 808 default local identity for the purpose of initiating security 809 contexts using the chosen mechanism, then the principal 810 corresponding to that identity shall be used; otherwise, 812 4) A user-configurable default identity should be used. 814 For the acceptor side of the context: 816 1) If there is only a single authorized principal identity capable of 817 accepting security contexts for the chosen mechanism, then that 818 principal shall be used; otherwise, 820 2) If the mechanism can determine the identity of the target 821 principal by examining the context-establishment token processed 822 during the accept method, and if the accepting application is 823 authorized to act as that principal for the purpose of accepting 824 security contexts using the chosen mechanism, then that principal 825 identity shall be used; otherwise, 827 3) If the mechanism supports context acceptance by any principal, and 828 if mutual authentication was not requested, any principal that the 829 application is authorized to accept security contexts under using 830 the chosen mechanism may be used; otherwise, 832 4) A user-configurable default identity shall be used. 834 The purpose of the above rules is to allow security contexts to be 835 established by both initiator and acceptor using the default behavior 836 whenever possible. Applications requesting default behavior are 837 likely to be more portable across mechanisms and implementations than 838 ones that instantiate an GSSCredential object representing a specific 839 identity. 841 4.9. Contexts 843 The GSSContext interface is used to represent one end of a GSS-API 844 security context, storing state information appropriate to that end 845 of the peer communication, including cryptographic state information. 846 The instantiation of the context object is done differently by the 847 initiator and the acceptor. After the context has been instantiated, 848 the initiator may choose to set various context options that will 849 determine the characteristics of the desired security context. When 850 all the application-desired characteristics have been set, the 851 initiator will call the initSecContext method, which will produce a 852 token for consumption by the peer's acceptSecContext method. It is 853 the responsibility of the application to deliver the authentication 854 token(s) between the peer applications for processing. Upon 855 completion of the context-establishment phase, context attributes can 856 be retrieved, by both the initiator and acceptor, using the accessor 857 methods. These will reflect the actual attributes of the established 858 context and might not match the initiator-requested values. If any 859 retrieved attribute does not match the desired value but it is 860 necessary for the application protocol, the application should 861 destroy the security context and not use it for application traffic. 862 Otherwise, at this point, the context can be used by the application 863 to apply cryptographic services to its data. 865 4.10. Authentication Tokens 867 A token is a caller-opaque type that GSS-API uses to maintain 868 synchronization between each end of the GSS-API security context. 869 The token is a cryptographically protected octet-string, generated by 870 the underlying mechanism at one end of a GSS-API security context for 871 use by the peer mechanism at the other end. Encapsulation (if 872 required) within the application protocol and transfer of the token 873 are the responsibility of the peer applications. 875 Java GSS-API uses byte arrays to represent authentication tokens. 877 4.11. Inter-Process Tokens 879 Certain GSS-API routines are intended to transfer data between 880 processes in multi-process programs. These routines use a caller- 881 opaque octet-string, generated by the GSS-API in one process for use 882 by the GSS-API in another process. The calling application is 883 responsible for transferring such tokens between processes. Note 884 that, while GSS-API implementors are encouraged to avoid placing 885 sensitive information within inter-process tokens, or to 886 cryptographically protect them, many implementations will be unable 887 to avoid placing key material or other sensitive data within them. 888 It is the application's responsibility to ensure that inter-process 889 tokens are protected in transit, and transferred only to processes 890 that are trustworthy. An inter-process token is represented using a 891 byte array emitted from the export method of the GSSContext 892 interface. The receiver of the inter-process token would initialize 893 an GSSContext object with this token to create a new context. Once a 894 context has been exported, the GSSContext object is invalidated and 895 is no longer available. 897 4.12. Error Reporting 899 RFC 2743 [RFC2743] defined the usage of major and minor status values 900 for the signaling of GSS-API errors. The major code, also called GSS 901 status code, is used to signal errors at the GSS-API level, 902 independent of the underlying mechanism(s). The minor status value 903 or Mechanism status code, is a mechanism-defined error value 904 indicating a mechanism-specific error code. 906 Java GSS-API uses exceptions implemented by the GSSException class to 907 signal both minor and major error values. Both mechanism-specific 908 errors and GSS-API level errors are signaled through instances of 909 this class. The usage of exceptions replaces the need for major and 910 minor codes to be used within the API calls. The GSSException class 911 also contains methods to obtain textual representations for both the 912 major and minor values, which is equivalent to the functionality of 913 gss_display_status. A GSSException object may also include an output 914 token that should be sent to the peer. 916 If an exception is thrown during context establishment, the context 917 negotiation has failed and the GSSContext object must be abandoned. 918 If it is thrown in a per-message call, the context can remain useful. 920 4.12.1. GSS Status Codes 922 GSS status codes indicate errors that are independent of the 923 underlying mechanism(s) used to provide the security service. The 924 errors that can be indicated via a GSS status code are generic API 925 routine errors (errors that are defined in the GSS-API 926 specification). These bindings take advantage of the Java exceptions 927 mechanism, thus, eliminating the need for calling errors. 929 A GSS status code indicates a single fatal generic API error from the 930 routine that has thrown the GSSException. Using exceptions announces 931 that a fatal error has occurred during the execution of the method. 932 The GSS-API operational model also allows for the signaling of 933 supplementary status information from the per-message calls. These 934 need to be handled as return values since using exceptions is not 935 appropriate for informatory or warning-like information. The methods 936 that are capable of producing supplementary information are the two 937 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 938 These methods fill the supplementary status codes in the MessageProp 939 object that was passed in. 941 A GSSException object, along with providing the functionality for 942 setting of the various error codes and translating them into textual 943 representation, also contains the definitions of all the numeric 944 error values. The following table lists the definitions of error 945 codes: 947 Table: GSS Status Codes 949 +----------------------+-------+------------------------------------+ 950 | Name | Value | Meaning | 951 +----------------------+-------+------------------------------------+ 952 | BAD_BINDINGS | 1 | Incorrect channel bindings were | 953 | | | supplied. | 954 | | | | 955 | BAD_MECH | 2 | An unsupported mechanism was | 956 | | | requested. | 957 | | | | 958 | BAD_NAME | 3 | An invalid name was supplied. | 959 | | | | 960 | BAD_NAMETYPE | 4 | A supplied name was of an | 961 | | | unsupported type. | 962 | | | | 963 | BAD_STATUS | 5 | An invalid status code was | 964 | | | supplied. | 965 | | | | 966 | BAD_MIC | 6 | A token had an invalid MIC. | 967 | | | | 968 | CONTEXT_EXPIRED | 7 | The context has expired. | 969 | | | | 970 | CREDENTIALS_EXPIRED | 8 | The referenced credentials have | 971 | | | expired. | 972 | | | | 973 | DEFECTIVE_CREDENTIAL | 9 | A supplied credential was invalid. | 974 | | | | 975 | DEFECTIVE_TOKEN | 10 | A supplied token was invalid. | 976 | | | | 977 | FAILURE | 11 | Miscellaneous failure, unspecified | 978 | | | at the GSS-API level. | 979 | | | | 980 | NO_CONTEXT | 12 | Invalid context has been supplied. | 981 | | | | 982 | NO_CRED | 13 | No credentials were supplied, or | 983 | | | the credentials were unavailable | 984 | | | or inaccessible. | 985 | | | | 986 | BAD_QOP | 14 | The quality-of-protection (QOP) | 987 | | | requested could not be provided. | 988 | | | | 989 | UNAUTHORIZED | 15 | The operation is forbidden by the | 990 | | | local security policy. | 991 | | | | 992 | UNAVAILABLE | 16 | The operation or option is | 993 | | | unavailable. | 994 | | | | 995 | DUPLICATE_ELEMENT | 17 | The requested credential element | 996 | | | already exists. | 997 | | | | 998 | NAME_NOT_MN | 18 | The provided name was not a | 999 | | | mechanism name. | 1000 +----------------------+-------+------------------------------------+ 1002 The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN, 1003 UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException only if 1004 detected during context establishment, in which case it is a fatal 1005 error. (During per-message calls, these values are indicated as 1006 supplementary information contained in the MessageProp object.) They 1007 are: 1009 +-----------------+-------+-----------------------------------------+ 1010 | Name | Value | Meaning | 1011 +-----------------+-------+-----------------------------------------+ 1012 | DUPLICATE_TOKEN | 19 | The token was a duplicate of an earlier | 1013 | | | version. | 1014 | | | | 1015 | OLD_TOKEN | 20 | The token's validity period has | 1016 | | | expired. | 1017 | | | | 1018 | UNSEQ_TOKEN | 21 | A later token has already been | 1019 | | | processed. | 1020 | | | | 1021 | GAP_TOKEN | 22 | The expected token was not received. | 1022 +-----------------+-------+-----------------------------------------+ 1024 The GSS major status code of FAILURE is used to indicate that the 1025 underlying mechanism detected an error for which no specific GSS 1026 status code is defined. The mechanism-specific status code can 1027 provide more details about the error. 1029 The different major status codes that can be contained in the 1030 GSSException object thrown by the methods in this specification are 1031 the same as the major status codes returned by the corresponding 1032 calls in RFC 2743 [RFC2743]. 1034 4.12.2. Mechanism-Specific Status Codes 1036 Mechanism-specific status codes are communicated in two ways, they 1037 are part of any GSSException thrown from the mechanism-specific layer 1038 to signal a fatal error, or they are part of the MessageProp object 1039 that the per-message calls use to signal non-fatal errors. 1041 A default value of 0 in either the GSSException object or the 1042 MessageProp object will be used to represent the absence of any 1043 mechanism-specific status code. 1045 4.12.3. Supplementary Status Codes 1047 Supplementary status codes are confined to the per-message methods of 1048 the GSSContext interface. Because of the informative nature of these 1049 errors it is not appropriate to use exceptions to signal them. 1050 Instead, the per-message operations of the GSSContext interface 1051 return these values in a MessageProp object. 1053 The MessageProp class defines query methods that return boolean 1054 values indicating the following supplementary states: 1056 Table: Supplementary Status Methods 1058 +------------------+------------------------------------------------+ 1059 | Method Name | Meaning when "true" is returned | 1060 +------------------+------------------------------------------------+ 1061 | isDuplicateToken | The token was a duplicate of an earlier token. | 1062 | | | 1063 | isOldToken | The token's validity period has expired. | 1064 | | | 1065 | isUnseqToken | A later token has already been processed. | 1066 | | | 1067 | isGapToken | An expected per-message token was not | 1068 | | received. | 1069 +------------------+------------------------------------------------+ 1071 A "true" return value for any of the above methods indicates that the 1072 token exhibited the specified property. The application must 1073 determine the appropriate course of action for these supplementary 1074 values. They are not treated as errors by the GSS-API. 1076 4.13. Names 1078 A name is used to identify a person or entity. GSS-API authenticates 1079 the relationship between a name and the entity claiming the name. 1081 Since different authentication mechanisms may employ different 1082 namespaces for identifying their principals, GSS-API's naming support 1083 is necessarily complex in multi-mechanism environments (or even in 1084 some single-mechanism environments where the underlying mechanism 1085 supports multiple namespaces). 1087 Two distinct conceptual representations are defined for names: 1089 1) A GSS-API form represented by implementations of the GSSName 1090 interface: A single GSSName object may contain multiple names from 1091 different namespaces, but all names should refer to the same 1092 entity. An example of such an internal name would be the name 1093 returned from a call to the getName method of the GSSCredential 1094 interface, when applied to a credential containing credential 1095 elements for multiple authentication mechanisms employing 1096 different namespaces. This GSSName object will contain a distinct 1097 name for the entity for each authentication mechanism. 1099 For GSS-API implementations supporting multiple namespaces, 1100 GSSName implementations must contain sufficient information to 1101 determine the namespace to which each primitive name belongs. 1103 2) Mechanism-specific contiguous byte array and string forms: 1104 Different GSSName initialization methods are provided to handle 1105 both byte array and string formats and to accommodate various 1106 calling applications and name types. These formats are capable of 1107 containing only a single name (from a single namespace). 1108 Contiguous string names are always accompanied by an object 1109 identifier specifying the namespace to which the name belongs, and 1110 their format is dependent on the authentication mechanism that 1111 employs that name. The string name forms are assumed to be 1112 printable, and may therefore be used by GSS-API applications for 1113 communication with their users. The byte array name formats are 1114 assumed to be in non-printable formats (e.g., the byte array 1115 returned from the export method of the GSSName interface). 1117 A GSSName object can be converted to a contiguous representation by 1118 using the toString method. This will guarantee that the name will be 1119 converted to a printable format. Different initialization methods in 1120 the GSSName interface are defined allowing support for multiple 1121 syntaxes for each supported namespace, and allowing users the freedom 1122 to choose a preferred name representation. The toString method 1123 should use an implementation-chosen printable syntax for each 1124 supported name type. To obtain the printable name type, 1125 getStringNameType method can be used. 1127 There is no guarantee that calling the toString method on the GSSName 1128 interface will produce the same string form as the original imported 1129 string name. Furthermore, it is possible that the name was not even 1130 constructed from a string representation. The same applies to 1131 namespace identifiers, which may not necessarily survive unchanged 1132 after a journey through the internal name form. An example of this 1133 might be a mechanism that authenticates X.500 names, but provides an 1134 algorithmic mapping of Internet DNS names into X.500. That 1135 mechanism's implementation of GSSName might, when presented with a 1136 DNS name, generate an internal name that contained both the original 1137 DNS name and the equivalent X.500 name. Alternatively, it might only 1138 store the X.500 name. In the latter case, the toString method of 1139 GSSName would most likely generate a printable X.500 name, rather 1140 than the original DNS name. 1142 The context acceptor can obtain a GSSName object representing the 1143 entity performing the context initiation (through the usage of 1144 getSrcName method). Since this name has been authenticated by a 1145 single mechanism, it contains only a single name (even if the 1146 internal name presented by the context initiator to the GSSContext 1147 object had multiple components). Such names are termed internal- 1148 mechanism names (or MNs), and the names emitted by GSSContext 1149 interface in the getSrcName and getTargName are always of this type. 1150 Since some applications may require MNs without wanting to incur the 1151 overhead of an authentication operation, creation methods are 1152 provided that take not only the name buffer and name type, but also 1153 the mechanism oid for which this name should be created. When 1154 dealing with an existing GSSName object, the canonicalize method may 1155 be invoked to convert a general internal name into an MN. 1157 GSSName objects can be compared using their equal method, which 1158 returns "true" if the two names being compared refer to the same 1159 entity. This is the preferred way to perform name comparisons 1160 instead of using the printable names that a given GSS-API 1161 implementation may support. Since GSS-API assumes that all primitive 1162 names contained within a given internal name refer to the same 1163 entity, equal can return "true" if the two names have at least one 1164 primitive name in common. If the implementation embodies knowledge 1165 of equivalence relationships between names taken from different 1166 namespaces, this knowledge may also allow successful comparisons of 1167 internal names containing no overlapping primitive elements. 1168 However, applications should note that to avoid surpising behavior, 1169 it is best to ensure that the names being compared are either both 1170 mechanism names for the same mechanism, or both internal names that 1171 are not mechanism names. This holds whether the equals method is 1172 used directly, or the export method is used to generate byte strings 1173 that are then compared byte-by-byte. 1175 When used in large access control lists, the overhead of creating a 1176 GSSName object on each name and invoking the equal method on each 1177 name from the Access Control List (ACL) may be prohibitive. As an 1178 alternative way of supporting this case, GSS-API defines a special 1179 form of the contiguous byte array name, which may be compared 1180 directly (byte by byte). Contiguous names suitable for comparison 1181 are generated by the export method. Exported names may be re- 1182 imported by using the byte array constructor and specifying the 1183 NT_EXPORT_NAME as the name type object identifier. The resulting 1184 GSSName name will also be a MN. 1186 The GSSName interface defines public static Oid objects representing 1187 the standard name types. Structurally, an exported name object 1188 consists of a header containing an OID identifying the mechanism that 1189 authenticated the name, and a trailer containing the name itself, 1190 where the syntax of the trailer is defined by the individual 1191 mechanism specification. Detailed description of the format is 1192 specified in the language-independent GSS-API specification 1193 [RFC2743]. 1195 Note that the results obtained by using the equals method will in 1196 general be different from those obtained by invoking canonicalize and 1197 export, and then comparing the byte array output. The first series 1198 of operation determines whether two (unauthenticated) names identify 1199 the same principal; the second whether a particular mechanism would 1200 authenticate them as the same principal. These two operations will 1201 in general give the same results only for MNs. 1203 It is important to note that the above are guidelines as to how 1204 GSSName implementations should behave, and are not intended to be 1205 specific requirements of how name objects must be implemented. The 1206 mechanism designers are free to decide on the details of their 1207 implementations of the GSSName interface as long as the behavior 1208 satisfies the above guidelines. 1210 4.14. Channel Bindings 1212 GSS-API supports the use of user-specified tags to identify a given 1213 context to the peer application. These tags are intended to be used 1214 to identify the particular communications channel that carries the 1215 context. Channel bindings are communicated to the GSS-API using the 1216 ChannelBinding object. The application may use byte arrays to 1217 specify the application data to be used in the channel binding as 1218 well as using instances of the InetAddress. The InetAddress for the 1219 initiator and/or acceptor can be used within an instance of a 1220 ChannelBinding. ChannelBinding can be set for the GSSContext object 1221 using the setChannelBinding method before the first call to init or 1222 accept has been performed. Unless the setChannelBinding method has 1223 been used to set the ChannelBinding for a GSSContext object, "null" 1224 ChannelBinding will be assumed. InetAddress is currently the only 1225 address type defined within the Java platform and as such, it is the 1226 only one supported within the ChannelBinding class. Applications 1227 that use other types of addresses can include them as part of the 1228 application-specific data. 1230 Conceptually, the GSS-API concatenates the initiator and acceptor 1231 address information, and the application-supplied byte array to form 1232 an octet-string. The mechanism calculates a Message Integrity Code 1233 (MIC) over this octet-string and binds the MIC to the context 1234 establishment token emitted by the init method of the GSSContext 1235 interface. The same bindings are set by the context acceptor for its 1236 GSSContext object and during processing of the accept method, a MIC 1237 is calculated in the same way. The calculated MIC is compared with 1238 that found in the token, and if the MICs differ, accept will throw a 1239 GSSException with the major code set to BAD_BINDINGS, and the context 1240 will not be established. Some mechanisms may include the actual 1241 channel binding data in the token (rather than just a MIC); 1242 applications should therefore not use confidential data as channel- 1243 binding components. 1245 Individual mechanisms may impose additional constraints on addresses 1246 that may appear in channel bindings. For example, a mechanism may 1247 verify that the initiator address field of the channel binding 1248 contains the correct network address of the host system. Portable 1249 applications should therefore ensure that they either provide correct 1250 information for the address fields, or omit the setting of the 1251 addressing information. 1253 4.15. Optional Parameters 1255 Whenever the application wishes to omit an optional parameter the 1256 "null" value shall be used. The detailed method descriptions 1257 indicate which parameters are optional. Method overloading has also 1258 been used as a technique to indicate default parameters. 1260 5. Introduction to GSS-API Classes and Interfaces 1262 This section presents a brief description of the classes and 1263 interfaces that constitute the GSS-API. The implementations of these 1264 are obtained from the CLASSPATH defined by the application. If Java 1265 GSS becomes part of the standard Java APIs, then these classes will 1266 be available by default on all systems as part of the JRE's system 1267 classes. 1269 This section also shows the corresponding RFC 2743 [RFC2743] 1270 functionality implemented by each of the classes. Detailed 1271 description of these classes and their methods is presented in 1272 section 6 1274 5.1. GSSManager Class 1276 This abstract class serves as a factory to instantiate 1277 implementations of the GSS-API interfaces and also provides methods 1278 to make queries about underlying security mechanisms. 1280 A default implementation can be obtained using the static method 1281 getInstance(). Applications that desire to provide their own 1282 implementation of the GSSManager class can simply extend the abstract 1283 class themselves. 1285 This class contains equivalents of the following RFC 2743 [RFC2743] 1286 routines: 1288 +----------------------------+-------------------------+------------+ 1289 | RFC 2743 Routine | Function | Section(s) | 1290 +----------------------------+-------------------------+------------+ 1291 | gss_import_name | Create an internal name | 6.1.5 - | 1292 | | from the supplied | 6.1.8 | 1293 | | information. | | 1294 | | | | 1295 | gss_acquire_cred | Acquire credential for | 6.1.9 - | 1296 | | use. | 6.1.11 | 1297 | | | | 1298 | gss_import_sec_context | Create a previously | 6.1.14 | 1299 | | exported context. | | 1300 | | | | 1301 | gss_indicate_mechs | List the mechanisms | 6.1.2 | 1302 | | supported by this GSS- | | 1303 | | API implementation. | | 1304 | | | | 1305 | gss_inquire_mechs_for_name | List the mechanisms | 6.1.4 | 1306 | | supporting the | | 1307 | | specified name type. | | 1308 | | | | 1309 | gss_inquire_names_for_mech | List the name types | 6.1.3 | 1310 | | supported by the | | 1311 | | specified mechanism. | | 1312 +----------------------------+-------------------------+------------+ 1314 5.2. GSSName Interface 1316 GSS-API names are represented in the Java bindings through the 1317 GSSName interface. Different name formats and their definitions are 1318 identified with Universal Object Identifiers (oids). The format of 1319 the names can be derived based on the unique oid of each name type. 1320 The following GSS-API routines are provided by the GSSName interface: 1322 +-----------------------+------------------------------+------------+ 1323 | RFC 2743 Routine | Function | Section(s) | 1324 +-----------------------+------------------------------+------------+ 1325 | gss_display_name | Convert internal name | 6.2.6 | 1326 | | representation to text | | 1327 | | format. | | 1328 | | | | 1329 | gss_compare_name | Compare two internal names. | 6.2.2, | 1330 | | | 6.2.3 | 1331 | | | | 1332 | gss_release_name | Release resources associated | N/A | 1333 | | with the internal name. | | 1334 | | | | 1335 | gss_canonicalize_name | Convert an internal name to | 6.2.4 | 1336 | | a mechanism name. | | 1337 | | | | 1338 | gss_export_name | Convert a mechanism name to | 6.2.5 | 1339 | | export format. | | 1340 | | | | 1341 | gss_duplicate_name | Create a copy of the | N/A | 1342 | | internal name. | | 1343 +-----------------------+------------------------------+------------+ 1345 The gss_release_name call is not provided as Java does its own 1346 garbage collection. The gss_duplicate_name call is also redundant; 1347 the GSSName interface has no mutator methods that can change the 1348 state of the object so it is safe for sharing across threads. 1350 5.3. GSSCredential Interface 1352 The GSSCredential interface is responsible for the encapsulation of 1353 GSS-API credentials. Credentials identify a single entity and 1354 provide the necessary cryptographic information to enable the 1355 creation of a context on behalf of that entity. A single credential 1356 may contain multiple mechanism-specific credentials, each referred to 1357 as a credential element. The GSSCredential interface provides the 1358 functionality of the following GSS-API routines: 1360 +--------------------------+---------------------------+------------+ 1361 | RFC 2743 Routine | Function | Section(s) | 1362 +--------------------------+---------------------------+------------+ 1363 | gss_add_cred | Constructs credentials | 6.3.11 | 1364 | | incrementally. | | 1365 | | | | 1366 | gss_inquire_cred | Obtain information about | 6.3.3 - | 1367 | | credential. | 6.3.10 | 1368 | | | | 1369 | gss_inquire_cred_by_mech | Obtain per-mechanism | 6.3.4 - | 1370 | | information about a | 6.3.9 | 1371 | | credential. | | 1372 | | | | 1373 | gss_release_cred | Dispose of credentials | 6.3.2 | 1374 | | after use. | | 1375 +--------------------------+---------------------------+------------+ 1377 5.4. GSSContext Interface 1379 This interface encapsulates the functionality of context-level calls 1380 required for security context establishment and management between 1381 peers as well as the per-message services offered to applications. A 1382 context is established between a pair of peers and allows the usage 1383 of security services on a per-message basis on application data. It 1384 is created over a single security mechanism. The GSSContext 1385 interface provides the functionality of the following GSS-API 1386 routines: 1388 +------------------------+-----------------------------+------------+ 1389 | RFC 2743 Routine | Function | Section(s) | 1390 +------------------------+-----------------------------+------------+ 1391 | gss_init_sec_context | Initiate the creation of a | 6.4.2 | 1392 | | security context with a | | 1393 | | peer. | | 1394 | | | | 1395 | gss_accept_sec_context | Accept a security context | 6.4.3 | 1396 | | initiated by a peer. | | 1397 | | | | 1398 | gss_delete_sec_context | Destroy a security context. | 6.4.5 | 1399 | | | | 1400 | gss_context_time | Obtain remaining context | 6.4.30 | 1401 | | time. | | 1402 | | | | 1403 | gss_inquire_context | Obtain context | 6.4.21 - | 1404 | | characteristics. | 6.4.35 | 1405 | | | | 1406 | gss_wrap_size_limit | Determine token-size limit | 6.4.6 | 1407 | | for gss_wrap. | | 1408 | | | | 1409 | gss_export_sec_context | Transfer security context | 6.4.11 | 1410 | | to another process. | | 1411 | | | | 1412 | gss_get_mic | Calculate a cryptographic | 6.4.9 | 1413 | | Message Integrity Code | | 1414 | | (MIC) for a message. | | 1415 | | | | 1416 | gss_verify_mic | Verify integrity on a | 6.4.10 | 1417 | | received message. | | 1418 | | | | 1419 | gss_wrap | Attach a MIC to a message | 6.4.7 | 1420 | | and optionally encrypt the | | 1421 | | message content. | | 1422 | | | | 1423 | gss_unwrap | Obtain a previously wrapped | 6.4.8 | 1424 | | application message | | 1425 | | verifying its integrity and | | 1426 | | optionally decrypting it. | | 1427 +------------------------+-----------------------------+------------+ 1429 The functionality offered by the gss_process_context_token routine 1430 has not been included in the Java bindings specification. The 1431 corresponding functionality of gss_delete_sec_context has also been 1432 modified to not return any peer tokens. This has been proposed in 1433 accordance to the recommendations stated in RFC 2743 [RFC2743]. 1434 GSSContext does offer the functionality of destroying the locally 1435 stored context information. 1437 5.5. MessageProp Class 1439 This helper class is used in the per-message operations on the 1440 context. An instance of this class is created by the application and 1441 then passed into the per-message calls. In some cases, the 1442 application conveys information to the GSS-API implementation through 1443 this object and in other cases the GSS-API returns information to the 1444 application by setting it in this object. See the description of the 1445 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1446 GSSContext interfaces for details. 1448 5.6. GSSException Class 1450 Exceptions are used in the Java bindings to signal fatal errors to 1451 the calling applications. This replaces the major and minor codes 1452 used in the C-bindings specification as a method of signaling 1453 failures. The GSSException class handles both minor and major codes, 1454 as well as their translation into textual representation. All GSS- 1455 API methods are declared as throwing this exception. 1457 +--------------------+----------------------------+-----------------+ 1458 | RFC 2743 Routine | Function | Section | 1459 +--------------------+----------------------------+-----------------+ 1460 | gss_display_status | Retrieve textual | 6.8.5, 6.8.6, | 1461 | | representation of error | 6.8.9, 6.8.10 | 1462 | | codes. | | 1463 +--------------------+----------------------------+-----------------+ 1465 5.7. Oid Class 1467 This utility class is used to represent Universal Object Identifiers 1468 and their associated operations. GSS-API uses object identifiers to 1469 distinguish between security mechanisms and name types. This class, 1470 aside from being used whenever an object identifier is needed, 1471 implements the following GSS-API functionality: 1473 +-------------------------+-------------------------------+---------+ 1474 | RFC 2743 Routine | Function | Section | 1475 +-------------------------+-------------------------------+---------+ 1476 | gss_test_oid_set_member | Determine if the specified | 6.7.5 | 1477 | | oid is part of a set of oids. | | 1478 +-------------------------+-------------------------------+---------+ 1480 5.8. ChannelBinding Class 1482 An instance of this class is used to specify channel binding 1483 information to the GSSContext object before the start of a security 1484 context establishment. The application may use a byte array to 1485 specify application data to be used in the channel binding as well as 1486 to use instances of the InetAddress. InetAddress is currently the 1487 only address type defined within the Java platform and as such, it is 1488 the only one supported within the ChannelBinding class. Applications 1489 that use other types of addresses can include them as part of the 1490 application data. 1492 6. Detailed GSS-API Class Description 1494 This section lists a detailed description of all the public methods 1495 that each of the GSS-API classes and interfaces must provide. 1497 6.1. public abstract class GSSManager 1499 The GSSManager class is an abstract class that serves as a factory 1500 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1501 also provides methods for applications to determine what mechanisms 1502 are available from the GSS implementation and what name types these 1503 mechanisms support. An instance of the default GSSManager subclass 1504 may be obtained through the static method getInstance(), but 1505 applications are free to instantiate other subclasses of GSSManager. 1507 All but one method in this class are declared abstract. This means 1508 that subclasses have to provide the complete implementation for those 1509 methods. The only exception to this is the static method 1510 getInstance(), which will have platform-specific code to return an 1511 instance of the default subclass. 1513 Platform providers of GSS are required not to add any constructors to 1514 this class, private, public, or protected. This will ensure that all 1515 subclasses invoke only the default constructor provided to the base 1516 class by the compiler. 1518 A subclass extending the GSSManager abstract class may be implemented 1519 as a modular provider-based layer that utilizes some well-known 1520 service provider specification. The GSSManager API provides the 1521 application with methods to set provider preferences on such an 1522 implementation. These methods also allow the implementation to throw 1523 a well-defined exception in case provider-based configuration is not 1524 supported. Applications that expect to be portable should be aware 1525 of this and recover cleanly by catching the exception. 1527 It is envisioned that there will be three most common ways in which 1528 providers will be used: 1530 1) The application does not care about what provider is used (the 1531 default case). 1533 2) The application wants a particular provider to be used 1534 preferentially, either for a particular mechanism or all the time, 1535 irrespective of the mechanism. 1537 3) The application wants to use the locally configured providers as 1538 far as possible, but if support is missing for one or more 1539 mechanisms, then it wants to fall back on its own provider. 1541 The GSSManager class has two methods that enable these modes of 1542 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1543 have the effect of creating an ordered list of pairs 1544 where each pair indicates a preference of provider for a given oid. 1546 The use of these methods does not require any knowledge of whatever 1547 service provider specification the GSSManager subclass follows. It 1548 is hoped that these methods will serve the needs of most 1549 applications. Additional methods may be added to an extended 1550 GSSManager that could be part of a service provider specification 1551 that is standardized later. 1553 When neither of the methods is called, the implementation should 1554 choose a default provider for each mechanism it supports. 1556 6.1.1. getInstance 1558 public static GSSManager getInstance() 1560 Returns the default GSSManager implementation. 1562 6.1.2. getMechs 1564 public abstract Oid[] getMechs() 1566 Returns an array of Oid objects indicating the mechanisms available 1567 to GSS-API callers. A "null" value is returned when no mechanism are 1568 available (an example of this would be when mechanism are dynamically 1569 configured, and currently no mechanisms are installed). 1571 6.1.3. getNamesForMech 1573 public abstract Oid[] getNamesForMech(Oid mech) 1574 throws GSSException 1576 Returns name type Oid's supported by the specified mechanism. 1578 Parameters: 1580 mech The Oid object for the mechanism to query. 1582 6.1.4. getMechsForName 1584 public abstract Oid[] getMechsForName(Oid nameType) 1586 Returns an array of Oid objects corresponding to the mechanisms that 1587 support the specific name type. "null" is returned when no mechanisms 1588 are found to support the specified name type. 1590 Parameters: 1592 nameType The Oid object for the name type. 1594 6.1.5. createName 1596 public abstract GSSName createName(String nameStr, Oid nameType) 1597 throws GSSException 1599 Factory method to convert a contiguous string name from the specified 1600 namespace to a GSSName object. In general, the GSSName object 1601 created will not be an MN; two examples that are exceptions to this 1602 are when the namespace type parameter indicates NT_EXPORT_NAME or 1603 when the GSS-API implementation is not multi-mechanism. 1605 Parameters: 1607 nameStr The string representing a printable form of the 1608 name to create. 1610 nameType The Oid specifying the namespace of the printable 1611 name is supplied. Note that nameType serves to 1612 describe and qualify the interpretation of the 1613 input nameStr, it does not necessarily imply a 1614 type for the output GSSName implementation. The 1615 "null" value can be used to specify that a 1616 mechanism-specific default printable syntax 1617 should be assumed by each mechanism that examines 1618 nameStr. 1620 6.1.6. createName 1622 public abstract GSSName createName(byte[] name, Oid nameType) 1623 throws GSSException 1625 Factory method to convert a contiguous byte array containing a name 1626 from the specified namespace to a GSSName object. In general, the 1627 GSSName object created will not be an MN; two examples that are 1628 exceptions to this are when the namespace type parameter indicates 1629 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1630 mechanism. 1632 Parameters: 1634 name The byte array containing the name to create. 1636 nameType The Oid specifying the namespace of the name 1637 supplied in the byte array. Note that nameType 1638 serves to describe and qualify the interpretation 1639 of the input name byte array; it does not 1640 necessarily imply a type for the output GSSName 1641 implementation. The "null" value can be used to 1642 specify that a mechanism-specific default syntax 1643 should be assumed by each mechanism that examines 1644 the byte array. 1646 6.1.7. createName 1648 public abstract GSSName createName(String nameStr, Oid nameType, 1649 Oid mech) throws GSSException 1651 Factory method to convert a contiguous string name from the specified 1652 namespace to a GSSName object that is a mechanism name (MN). In 1653 other words, this method is a utility that does the equivalent of two 1654 steps: the createName described in section 6.1.5, and then also the 1655 GSSName.canonicalize() described in section 6.2.4. 1657 Parameters: 1659 nameStr The string representing a printable form of the 1660 name to create. 1662 nameType The Oid specifying the namespace of the printable 1663 name supplied. Note that nameType serves to 1664 describe and qualify the interpretation of the 1665 input nameStr; it does not necessarily imply a 1666 type for the output GSSName implementation. The 1667 "null" value can be used to specify that a 1668 mechanism-specific default printable syntax 1669 should be assumed when the mechanism examines 1670 nameStr. 1672 mech Oid specifying the mechanism for which this name 1673 should be created. 1675 6.1.8. createName 1677 public abstract GSSName createName(byte[] name, Oid nameType, 1678 Oid mech) throws GSSException 1680 Factory method to convert a contiguous byte array containing a name 1681 from the specified namespace to a GSSName object that is an MN. In 1682 other words, this method is a utility that does the equivalent of two 1683 steps: the createName described in section 6.1.6, and then also the 1684 GSSName.canonicalize() described in section 6.2.4. 1686 Parameters: 1688 name The byte array representing the name to create. 1690 nameType The Oid specifying the namespace of the name 1691 supplied in the byte array. Note that nameType 1692 serves to describe and qualify the interpretation 1693 of the input name byte array, it does not 1694 necessarily imply a type for the output GSSName 1695 implementation. The "null" value can be used to 1696 specify that a mechanism-specific default syntax 1697 should be assumed by each mechanism that examines 1698 the byte array. 1700 mech Oid specifying the mechanism for which this name 1701 should be created. 1703 6.1.9. createCredential 1705 public abstract GSSCredential createCredential(int usage) 1706 throws GSSException 1708 Factory method for acquiring default credentials. This will cause 1709 the GSS-API to use system-specific defaults for the set of 1710 mechanisms, name, and a DEFAULT lifetime. 1712 Parameters: 1714 usage The intended usage for this credential object. 1715 The value of this parameter must be one of: 1717 GSSCredential.INITIATE_AND_ACCEPT(0), 1718 GSSCredential.INITIATE_ONLY(1), or 1719 GSSCredential.ACCEPT_ONLY(2) 1721 6.1.10. createCredential 1723 public abstract GSSCredential createCredential(GSSName aName, 1724 int lifetime, Oid mech, int usage) 1725 throws GSSException 1727 Factory method for acquiring a single mechanism credential. 1729 Parameters: 1731 aName Name of the principal for whom this credential is 1732 to be acquired. Use "null" to specify the 1733 default principal. 1735 lifetime The number of seconds that credentials should 1736 remain valid. Use 1737 GSSCredential.INDEFINITE_LIFETIME to request that 1738 the credentials have the maximum permitted 1739 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1740 request default credential lifetime. 1742 mech The oid of the desired mechanism. Use "(Oid) 1743 null" to request the default mechanism(s). 1745 usage The intended usage for this credential object. 1746 The value of this parameter must be one of: 1748 GSSCredential.INITIATE_AND_ACCEPT(0), 1749 GSSCredential.INITIATE_ONLY(1), or 1750 GSSCredential.ACCEPT_ONLY(2) 1752 6.1.11. createCredential 1754 public abstract GSSCredential createCredential(GSSName aName, 1755 int lifetime, Oid[] mechs, int usage) 1756 throws GSSException 1758 Factory method for acquiring credentials over a set of mechanisms. 1759 Acquires credentials for each of the mechanisms specified in the 1760 array called mechs. To determine the list of mechanisms' for which 1761 the acquisition of credentials succeeded, the caller should use the 1762 GSSCredential.getMechs() method. 1764 Parameters: 1766 aName Name of the principal for whom this credential is 1767 to be acquired. Use "null" to specify the 1768 default principal. 1770 lifetime The number of seconds that credentials should 1771 remain valid. Use 1772 GSSCredential.INDEFINITE_LIFETIME to request that 1773 the credentials have the maximum permitted 1774 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1775 request default credential lifetime. 1777 mechs The array of mechanisms over which the credential 1778 is to be acquired. Use "(Oid[]) null" for 1779 requesting a system-specific default set of 1780 mechanisms. 1782 usage The intended usage for this credential object. 1783 The value of this parameter must be one of: 1785 GSSCredential.INITIATE_AND_ACCEPT(0), 1786 GSSCredential.INITIATE_ONLY(1), or 1787 GSSCredential.ACCEPT_ONLY(2) 1789 6.1.12. createContext 1791 public abstract GSSContext createContext(GSSName peer, Oid mech, 1792 GSSCredential myCred, int lifetime) 1793 throws GSSException 1795 Factory method for creating a context on the initiator's side. 1796 Context flags may be modified through the mutator methods prior to 1797 calling GSSContext.initSecContext(). 1799 Parameters: 1801 peer Name of the target peer. 1803 mech Oid of the desired mechanism. Use "(Oid) null" 1804 to request the default mechanism. 1806 myCred Credentials of the initiator. Use "null" to act 1807 as a default initiator principal. 1809 lifetime The request lifetime, in seconds, for the 1810 context. Use GSSContext.INDEFINITE_LIFETIME and 1811 GSSContext.DEFAULT_LIFETIME to request indefinite 1812 or default context lifetime. 1814 6.1.13. createContext 1816 public abstract GSSContext createContext(GSSCredential myCred) 1817 throws GSSException 1819 Factory method for creating a context on the acceptor' side. The 1820 context's properties will be determined from the input token supplied 1821 to the accept method. 1823 Parameters: 1825 myCred Credentials for the acceptor. Use "null" to act 1826 as a default acceptor principal. 1828 6.1.14. createContext 1830 public abstract GSSContext createContext(byte[] interProcessToken) 1831 throws GSSException 1833 Factory method for importing a previously exported context. The 1834 context properties will be determined from the input token and can't 1835 be modified through the set methods. 1837 Parameters: 1839 interProcessToken The token previously emitted from the export 1840 method. 1842 6.1.15. addProviderAtFront 1844 public abstract void addProviderAtFront(Provider p, Oid mech) 1845 throws GSSException 1847 This method is used to indicate to the GSSManager that the 1848 application would like a particular provider to be used ahead of all 1849 others when support is desired for the given mechanism. When a value 1850 of "null" is used instead of an Oid for the mechanism, the GSSManager 1851 must use the indicated provider ahead of all others no matter what 1852 the mechanism is. Only when the indicated provider does not support 1853 the needed mechanism should the GSSManager move on to a different 1854 provider. 1856 Calling this method repeatedly preserves the older settings but 1857 lowers them in preference thus forming an ordered list of provider 1858 and Oid pairs that grows at the top. 1860 Calling addProviderAtFront with a null Oid will remove all previous 1861 preferences that were set for this provider in the GSSManager 1862 instance. Calling addProviderAtFront with a non-null Oid will remove 1863 any previous preference that was set using this mechanism and this 1864 provider together. 1866 If the GSSManager implementation does not support an SPI with a 1867 pluggable provider architecture, it should throw a GSSException with 1868 the status code GSSException.UNAVAILABLE to indicate that the 1869 operation is unavailable. 1871 Parameters: 1873 p The provider instance that should be used 1874 whenever support is needed for mech. 1876 mech The mechanism for which the provider is being 1877 set. 1879 6.1.15.1. addProviderAtFront Example Code 1881 Suppose an application desired that the provider A always be checked 1882 first when any mechanism is needed, it would call: 1884 1885 GSSManager mgr = GSSManager.getInstance(); 1886 // mgr may at this point have its own pre-configured list 1887 // of provider preferences. The following will prepend to 1888 // any such list: 1890 mgr.addProviderAtFront(A, null); 1891 1893 Now if it also desired that the mechanism of Oid m1 always be 1894 obtained from the provider B before the previously set A was checked, 1895 it would call: 1897 1898 mgr.addProviderAtFront(B, m1); 1899 1901 The GSSManager would then first check with B if m1 was needed. In 1902 case B did not provide support for m1, the GSSManager would continue 1903 on to check with A. If any mechanism m2 is needed where m2 is 1904 different from m1, then the GSSManager would skip B and check with A 1905 directly. 1907 Suppose, at a later time, the following call is made to the same 1908 GSSManager instance: 1910 1911 mgr.addProviderAtFront(B, null) 1912 1914 then the previous setting with the pair (B, m1) is subsumed by this 1915 and should be removed. Effectively, the list of preferences now 1916 becomes {(B, null), (A, null), ... //followed by the pre-configured 1917 list}. 1919 Please note, however, that the following call: 1921 1922 mgr.addProviderAtFront(A, m3) 1923 1925 does not subsume the previous setting of (A, null), and the list will 1926 effectively become {(A, m3), (B, null), (A, null), ...} 1928 6.1.16. addProviderAtEnd 1930 public abstract void addProviderAtEnd(Provider p, Oid mech) 1931 throws GSSException 1933 This method is used to indicate to the GSSManager that the 1934 application would like a particular provider to be used if no other 1935 provider can be found that supports the given mechanism. When a 1936 value of "null" is used instead of an Oid for the mechanism, the 1937 GSSManager must use the indicated provider for any mechanism. 1939 Calling this method repeatedly preserves the older settings, but 1940 raises them above newer ones in preference thus forming an ordered 1941 list of providers and Oid pairs that grows at the bottom. Thus, the 1942 older provider settings will be utilized first before this one is. 1944 If there are any previously existing preferences that conflict with 1945 the preference being set here, then the GSSManager should ignore this 1946 request. 1948 If the GSSManager implementation does not support an SPI with a 1949 pluggable provider architecture, it should throw a GSSException with 1950 the status code GSSException.UNAVAILABLE to indicate that the 1951 operation is unavailable. 1953 Parameters: 1955 p The provider instance that should be used 1956 whenever support is needed for mech. 1958 mech The mechanism for which the provider is being 1959 set. 1961 6.1.16.1. addProviderAtEnd Example Code 1963 Suppose an application desired that when a mechanism of Oid m1 is 1964 needed, the system default providers always be checked first, and 1965 only when they do not support m1 should a provider A be checked. It 1966 would then make the call: 1968 1969 GSSManager mgr = GSSManager.getInstance(); 1971 mgr.addProviderAtEnd(A, m1); 1972 1974 Now, if it also desired that for all mechanisms the provider B be 1975 checked after all configured providers have been checked, it would 1976 then call: 1978 1979 mgr.addProviderAtEnd(B, null); 1980 1982 Effectively, the list of preferences now becomes {..., (A, m1), (B, 1983 null)}. 1985 Suppose, at a later time, the following call is made to the same 1986 GSSManager instance: 1988 1989 mgr.addProviderAtEnd(B, m2) 1990 1992 then the previous setting with the pair (B, null) subsumes this; 1993 therefore, this request should be ignored. The same would happen if 1994 a request is made for the already existing pairs of (A, m1) or (B, 1995 null). 1997 Please note, however, that the following call: 1999 2000 mgr.addProviderAtEnd(A, null) 2001 2003 is not subsumed by the previous setting of (A, m1) and the list will 2004 effectively become {..., (A, m1), (B, null), (A, null)}. 2006 6.1.17. Example Code 2008 2009 GSSManager mgr = GSSManager.getInstance(); 2011 // What mechs are available to us? 2013 Oid[] supportedMechs = mgr.getMechs(); 2015 // Set a preference for the provider to be used when support 2016 // is needed for the mechanisms: 2017 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 2019 Oid krb = new Oid("1.2.840.113554.1.2.2"); 2020 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 2022 Provider p = (Provider) (new com.foo.security.Provider()); 2024 mgr.addProviderAtFront(p, krb); 2025 mgr.addProviderAtFront(p, spkm1); 2027 // What name types does this spkm implementation support? 2028 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 2029 2031 6.2. public interface GSSName 2033 This interface encapsulates a single GSS-API principal entity. 2034 Different name formats and their definitions are identified with 2035 Universal Object Identifiers (Oids). The format of the names can be 2036 derived based on the unique oid of its namespace type. 2038 6.2.1. Static Constants 2040 public static final Oid NT_HOSTBASED_SERVICE 2042 Oid indicating a host-based service name form. It is used to 2043 represent services associated with host computers. This name form is 2044 constructed using two elements, "service" and "hostname", as follows: 2046 service@hostname 2048 Values for the "service" element are registered with the IANA. It 2049 represents the following value: { iso(1) member-body(2) Unites 2050 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2051 service_name(4) } 2053 public static final Oid NT_USER_NAME 2054 Name type to indicate a named user on a local system. It represents 2055 the following value: { iso(1) member-body(2) United States(840) 2056 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2058 public static final Oid NT_MACHINE_UID_NAME 2060 Name type to indicate a numeric user identifier corresponding to a 2061 user on a local system (e.g., Uid). It represents the following 2062 value: { iso(1) member-body(2) United States(840) mit(113554) 2063 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2065 public static final Oid NT_STRING_UID_NAME 2067 Name type to indicate a string of digits representing the numeric 2068 user identifier of a user on a local system. It represents the 2069 following value: { iso(1) member-body(2) United States(840) 2070 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2072 public static final Oid NT_ANONYMOUS 2074 Name type for representing an anonymous entity. It represents the 2075 following value: { iso(1), org(3), dod(6), internet(1), security(5), 2076 nametypes(6), gss-anonymous-name(3) } 2078 public static final Oid NT_EXPORT_NAME 2080 Name type used to indicate an exported name produced by the export 2081 method. It represents the following value: { iso(1), org(3), dod(6), 2082 internet(1), security(5), nametypes(6), gss-api-exported-name(4) } 2084 6.2.2. equals 2086 public boolean equals(GSSName another) throws GSSException 2088 Compares two GSSName objects to determine whether they refer to the 2089 same entity. This method may throw a GSSException when the names 2090 cannot be compared. If either of the names represents an anonymous 2091 entity, the method will return "false". 2093 Parameters: 2095 another GSSName object with which to compare. 2097 6.2.3. equals 2099 public boolean equals(Object another) 2100 A variation of the equals method, described in section 6.2.2, that is 2101 provided to override the Object.equals() method that the implementing 2102 class will inherit. The behavior is exactly the same as that in 2103 section 6.2.2 except that no GSSException is thrown; instead, "false" 2104 will be returned in the situation where an error occurs. (Note that 2105 the Java language specification requires that two objects that are 2106 equal according to the equals(Object) method must return the same 2107 integer result when the hashCode() method is called on them.) 2109 Parameters: 2111 another GSSName object with which to compare. 2113 6.2.4. canonicalize 2115 public GSSName canonicalize(Oid mech) throws GSSException 2117 Creates a mechanism name (MN) from an arbitrary internal name. This 2118 is equivalent to using the factory methods described in sections 2119 6.1.7 or 6.1.8 that take the mechanism name as one of their 2120 parameters. 2122 Parameters: 2124 mech The oid for the mechanism for which the canonical 2125 form of the name is requested. 2127 6.2.5. export 2129 public byte[] export() throws GSSException 2131 Returns a canonical contiguous byte representation of a mechanism 2132 name (MN), suitable for direct, byte-by-byte comparison by 2133 authorization functions. If the name is not an MN, implementations 2134 may throw a GSSException with the NAME_NOT_MN status code. If an 2135 implementation chooses not to throw an exception, it should use some 2136 system-specific default mechanism to canonicalize the name and then 2137 export it. The format of the header of the output buffer is 2138 specified in RFC 2743 [RFC2743]. 2140 6.2.6. toString 2142 public String toString() 2144 Returns a textual representation of the GSSName object. To retrieve 2145 the printed name format, which determines the syntax of the returned 2146 string, the getStringNameType method can be used. 2148 6.2.7. getStringNameType 2150 public Oid getStringNameType() throws GSSException 2152 Returns the oid representing the type of name returned through the 2153 toString method. Using this oid, the syntax of the printable name 2154 can be determined. 2156 6.2.8. isAnonymous 2158 public boolean isAnonymous() 2160 Tests if this name object represents an anonymous entity. Returns 2161 "true" if this is an anonymous name. 2163 6.2.9. isMN 2165 public boolean isMN() 2167 Tests if this name object contains only one mechanism element and is 2168 thus a mechanism name as defined by RFC 2743 [RFC2743]. 2170 6.2.10. Example Code 2172 Included below are code examples utilizing the GSSName interface. 2173 The code below creates a GSSName, converts it to a mechanism name 2174 (MN), performs a comparison, obtains a printable representation of 2175 the name, exports it and then re-imports to obtain a new GSSName. 2177 2178 GSSManager mgr = GSSManager.getInstance(); 2180 // create a host-based service name 2181 GSSName name = mgr.createName("service@host", 2182 GSSName.NT_HOSTBASED_SERVICE); 2184 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 2186 GSSName mechName = name.canonicalize(krb5); 2188 // the above two steps are equivalent to the following 2189 GSSName mechName = mgr.createName("service@host", 2190 GSSName.NT_HOSTBASED_SERVICE, krb5); 2192 // perform name comparison 2193 if (name.equals(mechName)) 2194 print("Names are equals."); 2196 // obtain textual representation of name and its printable 2197 // name type 2198 print(mechName.toString() + 2199 mechName.getStringNameType().toString()); 2201 // export the name 2202 byte[] exportName = mechName.export(); 2204 // create a new name object from the exported buffer 2205 GSSName newName = mgr.createName(exportName, 2206 GSSName.NT_EXPORT_NAME); 2207 2209 6.3. public interface GSSCredential implements Cloneable 2211 This interface encapsulates the GSS-API credentials for an entity. A 2212 credential contains all the necessary cryptographic information to 2213 enable the creation of a context on behalf of the entity that it 2214 represents. It may contain multiple, distinct, mechanism-specific 2215 credential elements, each containing information for a specific 2216 security mechanism, but all referring to the same entity. 2218 A credential may be used to perform context initiation, acceptance, 2219 or both. 2221 GSS-API implementations must impose a local access-control policy on 2222 callers to prevent unauthorized callers from acquiring credentials to 2223 which they are not entitled. GSS-API credential creation is not 2224 intended to provide a "login to the network" function, as such a 2225 function would involve the creation of new credentials rather than 2226 merely acquiring a handle to existing credentials. Such functions, 2227 if required, should be defined in implementation-specific extensions 2228 to the API. 2230 If credential acquisition is time-consuming for a mechanism, the 2231 mechanism may choose to delay the actual acquisition until the 2232 credential is required (e.g., by GSSContext). Such mechanism- 2233 specific implementation decisions should be invisible to the calling 2234 application; thus, the query methods immediately following the 2235 creation of a credential object must return valid credential data, 2236 and may therefore incur the overhead of a deferred credential 2237 acquisition. 2239 Applications will create a credential object passing the desired 2240 parameters. The application can then use the query methods to obtain 2241 specific information about the instantiated credential object 2242 (equivalent to the gss_inquire routines). When the credential is no 2243 longer needed, the application should call the dispose (equivalent to 2244 gss_release_cred) method to release any resources held by the 2245 credential object and to destroy any cryptographically sensitive 2246 information. 2248 Classes implementing this interface also implement the Cloneable 2249 interface. This indicates that the class will support the clone() 2250 method that will allow the creation of duplicate credentials. This 2251 is useful when called just before the add() call to retain a copy of 2252 the original credential. 2254 6.3.1. Static Constants 2256 public static final int INITIATE_AND_ACCEPT 2258 Credential usage flag requesting that it be able to be used for both 2259 context initiation and acceptance. The value of this constant is 0. 2261 public static final int INITIATE_ONLY 2263 Credential usage flag requesting that it be able to be used for 2264 context initiation only. The value of this constant is 1. 2266 public static final int ACCEPT_ONLY 2268 Credential usage flag requesting that it be able to be used for 2269 context acceptance only. The value of this constant is 2. 2271 public static final int DEFAULT_LIFETIME 2272 A lifetime constant representing the default credential lifetime. 2273 The value of this constant is 0. 2275 public static final int INDEFINITE_LIFETIME 2277 A lifetime constant representing indefinite credential lifetime. The 2278 value of this constant is the maximum integer value in Java - 2279 Integer.MAX_VALUE. 2281 6.3.2. dispose 2283 public void dispose() throws GSSException 2285 Releases any sensitive information that the GSSCredential object may 2286 be containing. Applications should call this method as soon as the 2287 credential is no longer needed to minimize the time any sensitive 2288 information is maintained. 2290 6.3.3. getName 2292 public GSSName getName() throws GSSException 2294 Retrieves the name of the entity that the credential asserts. 2296 6.3.4. getName 2298 public GSSName getName(Oid mechOID) throws GSSException 2300 Retrieves a mechanism name of the entity that the credential asserts. 2301 Equivalent to calling canonicalize() on the name returned by section 2302 6.3.3. 2304 Parameters: 2306 mechOID The mechanism for which information should be 2307 returned. 2309 6.3.5. getRemainingLifetime 2311 public int getRemainingLifetime() throws GSSException 2313 Returns the remaining lifetime in seconds for a credential. The 2314 remaining lifetime is the minimum lifetime for any of the underlying 2315 credential mechanisms. A return value of 2316 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2317 not expire. A return value of 0 indicates that the credential is 2318 already expired. 2320 6.3.6. getRemainingInitLifetime 2322 public int getRemainingInitLifetime(Oid mech) throws GSSException 2324 Returns the remaining lifetime in seconds for the credential to 2325 remain capable of initiating security contexts under the specified 2326 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2327 indicates that the credential does not expire for context initiation. 2328 A return value of 0 indicates that the credential is already expired. 2330 Parameters: 2332 mechOID The mechanism for which information should be 2333 returned. 2335 6.3.7. getRemainingAcceptLifetime 2337 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2339 Returns the remaining lifetime in seconds for the credential to 2340 remain capable of accepting security contexts under the specified 2341 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2342 indicates that the credential does not expire for context acceptance. 2343 A return value of 0 indicates that the credential is already expired. 2345 Parameters: 2347 mechOID The mechanism for which information should be 2348 returned. 2350 6.3.8. getUsage 2352 public int getUsage() throws GSSException 2354 Returns the credential usage flag as a union over all mechanisms. 2355 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2356 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2358 Specifically, GSSCredential.INITIATE_AND_ACCEPT(0) should be returned 2359 as long as there exists one credential element allowing context 2360 initiation and one credential element allowing context acceptance. 2361 These two credential elements are not necessarily the same one, nor 2362 do they need to use the same mechanism(s). 2364 6.3.9. getUsage 2366 public int getUsage(Oid mechOID) throws GSSException 2368 Returns the credential usage flag for the specified mechanism only. 2369 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2370 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2372 Parameters: 2374 mechOID The mechanism for which information should be 2375 returned. 2377 6.3.10. getMechs 2379 public Oid[] getMechs() throws GSSException 2381 Returns an array of mechanisms supported by this credential. 2383 6.3.11. add 2385 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2386 Oid mech, int usage) throws GSSException 2388 Adds a mechanism-specific credential-element to an existing 2389 credential. This method allows the construction of credentials one 2390 mechanism at a time. 2392 This routine is envisioned to be used mainly by context acceptors 2393 during the creation of acceptance credentials, which are to be used 2394 with a variety of clients using different security mechanisms. 2396 This routine adds the new credential element "in-place". To add the 2397 element in a new credential, first call clone() to obtain a copy of 2398 this credential, then call its add() method. 2400 Parameters: 2402 aName Name of the principal for whom this credential is 2403 to be acquired. Use "null" to specify the 2404 default principal. 2406 initLifetime The number of seconds that credentials should 2407 remain valid for initiating of security contexts. 2408 Use GSSCredential.INDEFINITE_LIFETIME to request 2409 that the credentials have the maximum permitted 2410 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 2411 request default credential lifetime. 2413 acceptLifetime The number of seconds that credentials should 2414 remain valid for accepting of security contexts. 2416 Use GSSCredential.INDEFINITE_LIFETIME to request 2417 that the credentials 2418 have the maximum permitted lifetime. Use 2419 GSSCredential.DEFAULT_LIFETIME to request default 2420 credential lifetime. 2422 mech The mechanisms over which the credential is to be 2423 acquired. 2425 usage The intended usage for this credential object. 2426 The value of this parameter must be one of: 2428 GSSCredential.INITIATE_AND_ACCEPT(0), 2429 GSSCredential.INITIATE_ONLY(1), or 2430 GSSCredential.ACCEPT_ONLY(2) 2432 6.3.12. equals 2434 public boolean equals(Object another) 2436 Tests if this GSSCredential refers to the same entity as the supplied 2437 object. The two credentials must be acquired over the same 2438 mechanisms and must refer to the same principal. Returns "true" if 2439 the two GSSCredentials refer to the same entity; "false" otherwise. 2440 (Note that the Java language specification [JLS] requires that two 2441 objects that are equal according to the equals(Object) method must 2442 return the same integer result when the hashCode() method is called 2443 on them.) 2445 Parameters: 2447 another Another GSSCredential object for comparison. 2449 6.3.13. Example Code 2451 This example code demonstrates the creation of a GSSCredential 2452 implementation for a specific entity, querying of its fields, and its 2453 release when it is no longer needed. 2455 2456 GSSManager mgr = GSSManager.getInstance(); 2458 // start by creating a name object for the entity 2459 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2461 // now acquire credentials for the entity 2462 GSSCredential cred = mgr.createCredential(name, 2463 GSSCredential.ACCEPT_ONLY); 2465 // display credential information - name, remaining lifetime, 2466 // and the mechanisms it has been acquired over 2467 print(cred.getName().toString()); 2468 print(cred.getRemainingLifetime()); 2470 Oid[] mechs = cred.getMechs(); 2471 if (mechs != null) { 2472 for (int i = 0; i < mechs.length; i++) 2473 print(mechs[i].toString()); 2474 } 2475 // release system resources held by the credential 2476 cred.dispose(); 2477 2479 6.4. public interface GSSContext 2481 This interface encapsulates the GSS-API security context and provides 2482 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2483 available over the context. Security contexts are established 2484 between peers using locally acquired credentials. Multiple contexts 2485 may exist simultaneously between a pair of peers, using the same or 2486 different set of credentials. GSS-API functions in a manner 2487 independent of the underlying transport protocol and depends on its 2488 calling application to transport its tokens between peers. 2490 Before the context establishment phase is initiated, the context 2491 initiator may request specific characteristics desired of the 2492 established context. These can be set using the set methods. After 2493 the context is established, the caller can check the actual 2494 characteristic and services offered by the context using the query 2495 methods. 2497 The context establishment phase begins with the first call to the 2498 init method by the context initiator. During this phase, the 2499 initSecContext and acceptSecContext methods will produce GSS-API 2500 authentication tokens, which the calling application needs to send to 2501 its peer. If an error occurs at any point, an exception will get 2502 thrown and the code will start executing in a catch block where the 2503 exception may contain an output token that should be sent to the peer 2504 for debugging or informational purpose. If not, the normal flow of 2505 code continues and the application can make a call to the 2506 isEstablished() method. If this method returns "false" it indicates 2507 that a token is needed from its peer in order to continue the context 2508 establishment phase. A return value of "true" signals that the local 2509 end of the context is established. This may still require that a 2510 token be sent to the peer, if one is produced by GSS-API. During the 2511 context establishment phase, the isProtReady() method may be called 2512 to determine if the context can be used for the per-message 2513 operations. This allows applications to use per-message operations 2514 on contexts that aren't fully established. 2516 After the context has been established or the isProtReady() method 2517 returns "true", the query routines can be invoked to determine the 2518 actual characteristics and services of the established context. The 2519 application can also start using the per-message methods of wrap and 2520 getMIC to obtain cryptographic operations on application supplied 2521 data. 2523 When the context is no longer needed, the application should call 2524 dispose to release any system resources the context may be using. 2526 6.4.1. Static Constants 2528 public static final int DEFAULT_LIFETIME 2530 A lifetime constant representing the default context lifetime. The 2531 value of this constant is 0. 2533 public static final int INDEFINITE_LIFETIME 2535 A lifetime constant representing indefinite context lifetime. The 2536 value of this constant is the maximum integer value in Java - 2537 Integer.MAX_VALUE. 2539 6.4.2. initSecContext 2541 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2542 throws GSSException 2544 Called by the context initiator to start the context creation 2545 process. This method may return an output token that the application 2546 will need to send to the peer for processing by the accept call. The 2547 application can call isEstablished() to determine if the context 2548 establishment phase is complete for this peer. A return value of 2549 "false" from isEstablished() indicates that more tokens are expected 2550 to be supplied to the initSecContext() method. Note that it is 2551 possible that the initSecContext() method will return a token for the 2552 peer and isEstablished() will return "true" also. This indicates 2553 that the token needs to be sent to the peer, but the local end of the 2554 context is now fully established. 2556 Upon completion of the context establishment, the available context 2557 options may be queried through the get methods. 2559 A GSSException will be thrown if the call fails. Users should call 2560 its getOutputToken() method to find out if there is a token that can 2561 be sent to the acceptor to communicate the reason for the error. 2563 Parameters: 2565 inputBuf Token generated by the peer. This parameter is 2566 ignored on the first call. 2568 offset The offset within the inputBuf where the token 2569 begins. 2571 len The length of the token within the inputBuf 2572 (starting at the offset). 2574 6.4.3. acceptSecContext 2576 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2577 throws GSSException 2579 Called by the context acceptor upon receiving a token from the peer. 2581 This method may return an output token that the application will need 2582 to send to the peer for further processing by the init call. 2584 The "null" return value indicates that no token needs to be sent to 2585 the peer. The application can call isEstablished() to determine if 2586 the context establishment phase is complete for this peer. A return 2587 value of "false" from isEstablished() indicates that more tokens are 2588 expected to be supplied to this method. 2590 Note that it is possible that acceptSecContext() will return a token 2591 for the peer and isEstablished() will return "true" also. This 2592 indicates that the token needs to be sent to the peer, but the local 2593 end of the context is now fully established. 2595 Upon completion of the context establishment, the available context 2596 options may be queried through the get methods. 2598 A GSSException will be thrown if the call fails. Users should call 2599 its getOutputToken() method to find out if there is a token that can 2600 be sent to the initiator to communicate the reason for the error. 2602 Parameters: 2604 inTok Token generated by the peer. 2606 offset The offset within the inTok where the token 2607 begins. 2609 len The length of the token within the inTok 2610 (starting at the offset). 2612 6.4.4. isEstablished 2614 public boolean isEstablished() 2616 Used during context establishment to determine the state of the 2617 context. Returns "true" if this is a fully established context on 2618 the caller's side and no more tokens are needed from the peer. 2619 Should be called after a call to initSecContext() or 2620 acceptSecContext() when no GSSException is thrown. 2622 6.4.5. dispose 2624 public void dispose() throws GSSException 2626 Releases any system resources and cryptographic information stored in 2627 the context object. This will invalidate the context. 2629 6.4.6. getWrapSizeLimit 2631 public int getWrapSizeLimit(int qop, boolean confReq, 2632 int maxTokenSize) throws GSSException 2634 Returns the maximum message size that, if presented to the wrap 2635 method with the same confReq and qop parameters, will result in an 2636 output token containing no more than the maxTokenSize bytes. 2638 This call is intended for use by applications that communicate over 2639 protocols that impose a maximum message size. It enables the 2640 application to fragment messages prior to applying protection. 2642 GSS-API implementations are recommended but not required to detect 2643 invalid QOP values when getWrapSizeLimit is called. This routine 2644 guarantees only a maximum message size, not the availability of 2645 specific QOP values for message protection. 2647 Successful completion of this call does not guarantee that wrap will 2648 be able to protect a message of the computed length, since this 2649 ability may depend on the availability of system resources at the 2650 time that wrap is called. However, if the implementation itself 2651 imposes an upper limit on the length of messages that may be 2652 processed by wrap, the implementation should not return a value that 2653 is greater than this length. 2655 Parameters: 2657 qop Indicates the level of protection wrap will be 2658 asked to provide. 2660 confReq Indicates if wrap will be asked to provide 2661 privacy service. 2663 maxTokenSize The desired maximum size of the token emitted by 2664 wrap. 2666 6.4.7. wrap 2668 public byte[] wrap(byte[] inBuf, int offset, int len, 2669 MessageProp msgProp) throws GSSException 2671 Applies per-message security services over the established security 2672 context. The method will return a token with a cryptographic MIC and 2673 may optionally encrypt the specified inBuf. The returned byte array 2674 will contain both the MIC and the message. 2676 The MessageProp object is instantiated by the application and used to 2677 specify a QOP value that selects cryptographic algorithms, and a 2678 privacy service to optionally encrypt the message. The underlying 2679 mechanism that is used in the call may not be able to provide the 2680 privacy service. It sets the actual privacy service that it does 2681 provide in this MessageProp object, which the caller should then 2682 query upon return. If the mechanism is not able to provide the 2683 requested QOP, it throws a GSSException with the BAD_QOP code. 2685 Since some application-level protocols may wish to use tokens emitted 2686 by wrap to provide "secure framing", implementations should support 2687 the wrapping of zero-length messages. 2689 The application will be responsible for sending the token to the 2690 peer. 2692 Parameters: 2694 inBuf Application data to be protected. 2696 offset The offset within the inBuf where the data 2697 begins. 2699 len The length of the data within the inBuf (starting 2700 at the offset). 2702 msgProp Instance of MessageProp that is used by the 2703 application to set the desired QOP and privacy 2704 state. Set the desired QOP to 0 to request the 2705 default QOP. Upon return from this method, this 2706 object will contain the actual privacy state that 2707 was applied to the message by the underlying 2708 mechanism. 2710 6.4.8. unwrap 2712 public byte[] unwrap(byte[] inBuf, int offset, int len, 2713 MessageProp msgProp) throws GSSException 2715 Used by the peer application to process tokens generated with the 2716 wrap call. The method will return the message supplied in the peer 2717 application to the wrap call, verifying the embedded MIC. 2719 The MessageProp object is instantiated by the application and is used 2720 by the underlying mechanism to return information to the caller such 2721 as the QOP, whether confidentiality was applied to the message, and 2722 other supplementary message state information. 2724 Since some application-level protocols may wish to use tokens emitted 2725 by wrap to provide "secure framing", implementations should support 2726 the wrapping and unwrapping of zero-length messages. 2728 Parameters: 2730 inBuf GSS-API wrap token received from peer. 2732 offset The offset within the inBuf where the token 2733 begins. 2735 len The length of the token within the inBuf 2736 (starting at the offset). 2738 msgProp Upon return from the method, this object will 2739 contain the applied QOP, the privacy state of the 2740 message, and supplementary information, described 2741 in section 4.12.3, stating whether the token was 2742 a duplicate, old, out of sequence, or arriving 2743 after a gap. 2745 6.4.9. getMIC 2747 public byte[] getMIC(byte[] inMsg, int offset, int len, 2748 MessageProp msgProp) throws GSSException 2750 Returns a token containing a cryptographic MIC for the supplied 2751 message for transfer to the peer application. Unlike wrap, which 2752 encapsulates the user message in the returned token, only the message 2753 MIC is returned in the output token. 2755 Note that privacy can only be applied through the wrap call. 2757 Since some application-level protocols may wish to use tokens emitted 2758 by getMIC to provide "secure framing", implementations should support 2759 derivation of MICs from zero-length messages. 2761 Parameters: 2763 inMsg Message over which to generate MIC. 2765 offset The offset within the inMsg where the token 2766 begins. 2768 len The length of the token within the inMsg 2769 (starting at the offset). 2771 msgProp Instance of MessageProp that is used by the 2772 application to set the desired QOP. Set the 2773 desired QOP to 0 in msgProp to request the 2774 default QOP. Alternatively, pass in "null" for 2775 msgProp to request default QOP. 2777 6.4.10. verifyMIC 2779 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 2780 byte[] inMsg, int msgOffset, int msgLen, 2781 MessageProp msgProp) throws GSSException 2783 Verifies the cryptographic MIC, contained in the token parameter, 2784 over the supplied message. 2786 The MessageProp object is instantiated by the application and is used 2787 by the underlying mechanism to return information to the caller such 2788 as the QOP indicating the strength of protection that was applied to 2789 the message and other supplementary message state information. 2791 Since some application-level protocols may wish to use tokens emitted 2792 by getMIC to provide "secure framing", implementations should support 2793 the calculation and verification of MICs over zero-length messages. 2795 Parameters: 2797 inTok Token generated by peer's getMIC method. 2799 tokOffset The offset within the inTok where the token 2800 begins. 2802 tokLen The length of the token within the inTok 2803 (starting at the offset). 2805 inMsg Application message over which to verify the 2806 cryptographic MIC. 2808 msgOffset The offset within the inMsg where the message 2809 begins. 2811 msgLen The length of the message within the inMsg 2812 (starting at the offset). 2814 msgProp Upon return from the method, this object will 2815 contain the applied QOP and supplementary 2816 information, described in section 4.12.3, stating 2817 whether the token was a duplicate, old, out of 2818 sequence, or arriving after a gap. The 2819 confidentiality state will be set to "false". 2821 6.4.11. export 2823 public byte[] export() throws GSSException 2825 Provided to support the sharing of work between multiple processes. 2826 This routine will typically be used by the context acceptor, in an 2827 application where a single process receives incoming connection 2828 requests and accepts security contexts over them, then passes the 2829 established context to one or more other processes for message 2830 exchange. 2832 This method deactivates the security context and creates an inter- 2833 process token which, when passed to the byte array constructor of the 2834 GSSContext interface in another process, will re-activate the context 2835 in the second process. Only a single instantiation of a given 2836 context may be active at any one time; a subsequent attempt by a 2837 context exporter to access the exported security context will fail. 2839 The implementation may constrain the set of processes by which the 2840 inter-process token may be imported, either as a function of local 2841 security policy, or as a result of implementation decisions. For 2842 example, some implementations may constrain contexts to be passed 2843 only between processes that run under the same account, or which are 2844 part of the same process group. 2846 The inter-process token may contain security-sensitive information 2847 (for example, cryptographic keys). While mechanisms are encouraged 2848 to either avoid placing such sensitive information within inter- 2849 process tokens or to encrypt the token before returning it to the 2850 application, in a typical GSS-API implementation, this may not be 2851 possible. Thus, the application must take care to protect the inter- 2852 process token, and ensure that any process to which the token is 2853 transferred is trustworthy. 2855 6.4.12. requestMutualAuth 2857 public void requestMutualAuth(boolean state) throws GSSException 2859 Sets the request state of the mutual authentication flag for the 2860 context. This method is only valid before the context creation 2861 process begins and only for the initiator. 2863 Parameters: 2865 state Boolean representing if mutual authentication 2866 should be requested during context establishment. 2868 6.4.13. requestReplayDet 2870 public void requestReplayDet(boolean state) throws GSSException 2872 Sets the request state of the replay detection service for the 2873 context. This method is only valid before the context creation 2874 process begins and only for the initiator. 2876 Parameters: 2878 state Boolean representing if replay detection is 2879 desired over the established context. 2881 6.4.14. requestSequenceDet 2883 public void requestSequenceDet(boolean state) throws GSSException 2884 Sets the request state for the sequence checking service of the 2885 context. This method is only valid before the context creation 2886 process begins and only for the initiator. 2888 Parameters: 2890 state Boolean representing if sequence detection is 2891 desired over the established context. 2893 6.4.15. requestCredDeleg 2895 public void requestCredDeleg(boolean state) throws GSSException 2897 Sets the request state for the credential delegation flag for the 2898 context. This method is only valid before the context creation 2899 process begins and only for the initiator. 2901 Parameters: 2903 state Boolean representing if credential delegation is 2904 desired. 2906 6.4.16. requestAnonymity 2908 public void requestAnonymity(boolean state) throws GSSException 2910 Requests anonymous support over the context. This method is only 2911 valid before the context creation process begins and only for the 2912 initiator. 2914 Parameters: 2916 state Boolean representing if anonymity support is 2917 requested. 2919 6.4.17. requestConf 2921 public void requestConf(boolean state) throws GSSException 2923 Requests that confidentiality service be available over the context. 2924 This method is only valid before the context creation process begins 2925 and only for the initiator. 2927 Parameters: 2929 state Boolean indicating if confidentiality services 2930 are to be requested for the context. 2932 6.4.18. requestInteg 2934 public void requestInteg(boolean state) throws GSSException 2936 Requests that integrity services be available over the context. This 2937 method is only valid before the context creation process begins and 2938 only for the initiator. 2940 Parameters: 2942 state Boolean indicating if integrity services are to 2943 be requested for the context. 2945 6.4.19. requestLifetime 2947 public void requestLifetime(int lifetime) throws GSSException 2949 Sets the desired lifetime for the context in seconds. This method is 2950 only valid before the context creation process begins and only for 2951 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 2952 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 2953 lifetime. 2955 Parameters: 2957 lifetime The desired context lifetime in seconds. 2959 6.4.20. setChannelBinding 2961 public void setChannelBinding(ChannelBinding cb) throws GSSException 2963 Sets the channel bindings to be used during context establishment. 2964 This method is only valid before the context creation process begins. 2966 Parameters: 2968 cb Channel bindings to be used. 2970 6.4.21. getCredDelegState 2972 public boolean getCredDelegState() 2974 Returns the state of the delegated credentials for the context. When 2975 issued before context establishment is completed or when the 2976 isProtReady method returns "false", it returns the desired state; 2977 otherwise, it will indicate the actual state over the established 2978 context. 2980 6.4.22. getMutualAuthState 2982 public boolean getMutualAuthState() 2984 Returns the state of the mutual authentication option for the 2985 context. When issued before context establishment completes or when 2986 the isProtReady method returns "false", it returns the desired state; 2987 otherwise, it will indicate the actual state over the established 2988 context. 2990 6.4.23. getReplayDetState 2992 public boolean getReplayDetState() 2994 Returns the state of the replay detection option for the context. 2995 When issued before context establishment completes or when the 2996 isProtReady method returns "false", it returns the desired state; 2997 otherwise, it will indicate the actual state over the established 2998 context. 3000 6.4.24. getSequenceDetState 3002 public boolean getSequenceDetState() 3004 Returns the state of the sequence detection option for the context. 3005 When issued before context establishment completes or when the 3006 isProtReady method returns "false", it returns the desired state; 3007 otherwise, it will indicate the actual state over the established 3008 context. 3010 6.4.25. getAnonymityState 3012 public boolean getAnonymityState() 3014 Returns "true" if this is an anonymous context. When issued before 3015 context establishment completes or when the isProtReady method 3016 returns "false", it returns the desired state; otherwise, it will 3017 indicate the actual state over the established context. 3019 6.4.26. isTransferable 3021 public boolean isTransferable() throws GSSException 3023 Returns "true" if the context is transferable to other processes 3024 through the use of the export method. This call is only valid on 3025 fully established contexts. 3027 6.4.27. isProtReady 3029 public boolean isProtReady() 3031 Returns "true" if the per-message operations can be applied over the 3032 context. Some mechanisms may allow the usage of per-message 3033 operations before the context is fully established. This will also 3034 indicate that the get methods will return actual context state 3035 characteristics instead of the desired ones. 3037 6.4.28. getConfState 3039 public boolean getConfState() 3041 Returns the confidentiality service state over the context. When 3042 issued before context establishment completes or when the isProtReady 3043 method returns "false", it returns the desired state; otherwise, it 3044 will indicate the actual state over the established context. 3046 6.4.29. getIntegState 3048 public boolean getIntegState() 3050 Returns the integrity service state over the context. When issued 3051 before context establishment completes or when the isProtReady method 3052 returns "false", it returns the desired state; otherwise, it will 3053 indicate the actual state over the established context. 3055 6.4.30. getLifetime 3057 public int getLifetime() 3059 Returns the context lifetime in seconds. When issued before context 3060 establishment completes or when the isProtReady method returns 3061 "false", it returns the desired lifetime; otherwise, it will indicate 3062 the remaining lifetime for the context. 3064 6.4.31. getSrcName 3066 public GSSName getSrcName() throws GSSException 3068 Returns the name of the context initiator. This call is valid only 3069 after the context is fully established or the isProtReady method 3070 returns "true". It is guaranteed to return an MN. 3072 6.4.32. getTargName 3074 public GSSName getTargName() throws GSSException 3076 Returns the name of the context target (acceptor). This call is 3077 valid only after the context is fully established or the isProtReady 3078 method returns "true". It is guaranteed to return an MN. 3080 6.4.33. getMech 3082 public Oid getMech() throws GSSException 3084 Returns the mechanism oid for this context. This method may be 3085 called before the context is fully established, but the mechanism 3086 returned may change on successive calls in negotiated mechanism case. 3088 6.4.34. getDelegCred 3090 public GSSCredential getDelegCred() throws GSSException 3092 Returns the delegated credential object on the acceptor's side. To 3093 check for availability of delegated credentials call 3094 getDelegCredState. This call is only valid on fully established 3095 contexts. 3097 6.4.35. isInitiator 3099 public boolean isInitiator() throws GSSException 3101 Returns "true" if this is the initiator of the context. This call is 3102 only valid after the context creation process has started. 3104 6.4.36. Example Code 3106 The example code presented below demonstrates the usage of the 3107 GSSContext interface for the initiating peer. Different operations 3108 on the GSSContext object are presented, including: object 3109 instantiation, setting of desired flags, context establishment, query 3110 of actual context flags, per-message operations on application data, 3111 and finally context deletion. 3113 3114 GSSManager mgr = GSSManager.getInstance(); 3116 // start by creating the name for a service entity 3117 GSSName targetName = mgr.createName("service@host", 3118 GSSName.NT_HOSTBASED_SERVICE); 3119 // create a context using default credentials for the above entity 3120 // and the implementation-specific default mechanism 3121 GSSContext context = mgr.createContext(targetName, 3122 null, /* default mechanism */ 3123 null, /* default credentials */ 3124 GSSContext.INDEFINITE_LIFETIME); 3126 // set desired context options - all others are "false" by default 3127 context.requestConf(true); 3128 context.requestMutualAuth(true); 3129 context.requestReplayDet(true); 3130 context.requestSequenceDet(true); 3132 // establish a context between peers - using byte arrays 3133 byte[]inTok = new byte[0]; 3135 try { 3136 do { 3137 byte[] outTok = context.initSecContext(inTok, 0, 3138 inTok.length); 3140 // send the token if present 3141 if (outTok != null) 3142 sendToken(outTok); 3144 // check if we should expect more tokens 3145 if (context.isEstablished()) 3146 break; 3148 // another token expected from peer 3149 inTok = readToken(); 3151 } while (true); 3153 } catch (GSSException e) { 3154 print("GSSAPI error: " + e.getMessage()); 3156 // If the exception contains an output token, 3157 // it should be sent to the acceptor. 3158 byte[] outTok = e.getOutputToken(); 3159 if (outTok != null) { 3160 sendToken(outTok); 3161 } 3163 return; 3164 } 3166 // display context information 3167 print("Remaining lifetime in seconds = " + context.getLifetime()); 3168 print("Context mechanism = " + context.getMech().toString()); 3169 print("Initiator = " + context.getSrcName().toString()); 3170 print("Acceptor = " + context.getTargName().toString()); 3172 if (context.getConfState()) 3173 print("Confidentiality security service available"); 3175 if (context.getIntegState()) 3176 print("Integrity security service available"); 3178 // perform wrap on an application-supplied message, appMsg, 3179 // using QOP = 0, and requesting privacy service 3180 byte[] appMsg ... 3182 MessageProp mProp = new MessageProp(0, true); 3184 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 3186 if (mProp.getPrivacy()) 3187 print("Message protected with privacy."); 3189 sendToken(tok); 3191 // release the local end of the context 3192 context.dispose(); 3193 3195 6.5. public class MessageProp 3197 This is a utility class used within the per-message GSSContext 3198 methods to convey per-message properties. 3200 When used with the GSSContext interface's wrap and getMIC methods, an 3201 instance of this class is used to indicate the desired QOP and to 3202 request if confidentiality services are to be applied to caller 3203 supplied data (wrap only). To request default QOP, the value of 0 3204 should be used for QOP. A QOP is an integer value defined by an 3205 mechanism. 3207 When used with the unwrap and verifyMIC methods of the GSSContext 3208 interface, an instance of this class will be used to indicate the 3209 applied QOP and confidentiality services over the supplied message. 3210 In the case of verifyMIC, the confidentiality state will always be 3211 "false". Upon return from these methods, this object will also 3212 contain any supplementary status values applicable to the processed 3213 token. The supplementary status values can indicate old tokens, out 3214 of sequence tokens, gap tokens, or duplicate tokens. 3216 6.5.1. Constructors 3218 public MessageProp(boolean privState) 3220 Constructor that sets QOP to 0 indicating that the default QOP is 3221 requested. 3223 Parameters: 3225 privState The desired privacy state. "true" for privacy and 3226 "false" for integrity only. 3228 public MessageProp(int qop, boolean privState) 3230 Constructor that sets the values for the qop and privacy state. 3232 Parameters: 3234 qop The desired QOP. Use 0 to request a default QOP. 3236 privState The desired privacy state. "true" for privacy and 3237 "false" for integrity only. 3239 6.5.2. getQOP 3241 public int getQOP() 3243 Retrieves the QOP value. 3245 6.5.3. getPrivacy 3247 public boolean getPrivacy() 3249 Retrieves the privacy state. 3251 6.5.4. getMinorStatus 3253 public int getMinorStatus() 3255 Retrieves the minor status that the underlying mechanism might have 3256 set. 3258 6.5.5. getMinorString 3260 public String getMinorString() 3262 Returns a string explaining the mechanism-specific error code. "null" 3263 will be returned when no mechanism error code has been set. 3265 6.5.6. setQOP 3267 public void setQOP(int qopVal) 3269 Sets the QOP value. 3271 Parameters: 3273 qopVal The QOP value to be set. Use 0 to request a 3274 default QOP value. 3276 6.5.7. setPrivacy 3278 public void setPrivacy(boolean privState) 3280 Sets the privacy state. 3282 Parameters: 3284 privState The privacy state to set. 3286 6.5.8. isDuplicateToken 3288 public boolean isDuplicateToken() 3290 Returns "true" if this is a duplicate of an earlier token. 3292 6.5.9. isOldToken 3294 public boolean isOldToken() 3296 Returns "true" if the token's validity period has expired. 3298 6.5.10. isUnseqToken 3300 public boolean isUnseqToken() 3302 Returns "true" if a later token has already been processed. 3304 6.5.11. isGapToken 3306 public boolean isGapToken() 3308 Returns "true" if an expected per-message token was not received. 3310 6.5.12. setSupplementaryStates 3312 public void setSupplementaryStates(boolean duplicate, 3313 boolean old, boolean unseq, boolean gap, 3314 int minorStatus, String minorString) 3316 This method sets the state for the supplementary information flags 3317 and the minor status in MessageProp. It is not used by the 3318 application but by the GSS implementation to return this information 3319 to the caller of a per-message context method. 3321 Parameters: 3323 duplicate "true" if the token was a duplicate of an earlier 3324 token; otherwise, "false". 3326 old "true" if the token's validity period has 3327 expired; otherwise, "false". 3329 unseq "true" if a later token has already been 3330 processed; otherwise, "false". 3332 gap "true" if one or more predecessor tokens have not 3333 yet been successfully processed; otherwise, 3334 "false". 3336 minorStatus The integer minor status code that the underlying 3337 mechanism wants to set. 3339 minorString The textual representation of the minorStatus 3340 value. 3342 6.6. public class ChannelBinding 3344 The GSS-API accommodates the concept of caller-provided channel 3345 binding information. Channel bindings are used to strengthen the 3346 quality with which peer entity authentication is provided during 3347 context establishment. They enable the GSS-API callers to bind the 3348 establishment of the security context to relevant characteristics 3349 like addresses or to application-specific data. 3351 The caller initiating the security context must determine the 3352 appropriate channel binding values to set in the GSSContext object. 3353 The acceptor must provide an identical binding in order to validate 3354 that received tokens possess correct channel-related characteristics. 3356 Use of channel bindings is optional in GSS-API. Since channel- 3357 binding information may be transmitted in context establishment 3358 tokens, applications should therefore not use confidential data as 3359 channel-binding components. 3361 6.6.1. Constructors 3363 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3364 byte[] appData) 3366 Create a ChannelBinding object with user-supplied address information 3367 and data. "null" values can be used for any fields that the 3368 application does not want to specify. 3370 Parameters: 3372 initAddr The address of the context initiator. "null" 3373 value can be supplied to indicate that the 3374 application does not want to set this value. 3376 acceptAddr The address of the context acceptor. "null" value 3377 can be supplied to indicate that the application 3378 does not want to set this value. 3380 appData Application-supplied data to be used as part of 3381 the channel bindings. "null" value can be 3382 supplied to indicate that the application does 3383 not want to set this value. 3385 public ChannelBinding(byte[] appData) 3387 Creates a ChannelBinding object without any addressing information. 3389 Parameters: 3391 appData Application supplied data to be used as part of 3392 the channel bindings. 3394 6.6.2. getInitiatorAddress 3396 public InetAddress getInitiatorAddress() 3398 Returns the initiator's address for this channel binding. "null" is 3399 returned if the address has not been set. 3401 6.6.3. getAcceptorAddress 3403 public InetAddress getAcceptorAddress() 3404 Returns the acceptor's address for this channel binding. "null" is 3405 returned if the address has not been set. 3407 6.6.4. getApplicationData 3409 public byte[] getApplicationData() 3411 Returns application data being used as part of the ChannelBinding. 3412 "null" is returned if no application data has been specified for the 3413 channel binding. 3415 6.6.5. equals 3417 public boolean equals(Object obj) 3419 Returns "true" if two channel bindings match. (Note that the Java 3420 language specification requires that two objects that are equal 3421 according to the equals(Object) method must return the same integer 3422 result when the hashCode() method is called on them.) 3424 Parameters: 3426 obj Another channel binding with which to compare. 3428 6.7. public class Oid 3430 This class represents Universal Object Identifiers (Oids) and their 3431 associated operations. 3433 Oids are hierarchically globally interpretable identifiers used 3434 within the GSS-API framework to identify mechanisms and name formats. 3436 The structure and encoding of Oids is defined in ISOIEC-8824 and 3437 ISOIEC-8825. For example, the Oid representation of the Kerberos v5 3438 mechanism is "1.2.840.113554.1.2.2". 3440 The GSSName name class contains public static Oid objects 3441 representing the standard name types defined in GSS-API. 3443 6.7.1. Constructors 3445 public Oid(String strOid) throws GSSException 3447 Creates an Oid object from a string representation of its integer 3448 components (e.g., "1.2.840.113554.1.2.2"). 3450 Parameters: 3452 strOid The string representation for the oid. 3454 public Oid(InputStream derOid) throws GSSException 3456 Creates an Oid object from its DER encoding. This refers to the full 3457 encoding including tag and length. The structure and encoding of 3458 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3459 identical in functionality to its byte array counterpart. 3461 Parameters: 3463 derOid Stream containing the DER-encoded oid. 3465 public Oid(byte[] DEROid) throws GSSException 3467 Creates an Oid object from its DER encoding. This refers to the full 3468 encoding including tag and length. The structure and encoding of 3469 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3470 identical in functionality to its byte array counterpart. 3472 Parameters: 3474 derOid Byte array storing a DER-encoded oid. 3476 6.7.2. toString 3478 public String toString() 3480 Returns a string representation of the oid's integer components in 3481 dot separated notation (e.g., "1.2.840.113554.1.2.2"). 3483 6.7.3. equals 3485 public boolean equals(Object Obj) 3487 Returns "true" if the two Oid objects represent the same oid value. 3488 (Note that the Java language specification [JLS] requires that two 3489 objects that are equal according to the equals(Object) method must 3490 return the same integer result when the hashCode() method is called 3491 on them.) 3493 Parameters: 3495 obj Another Oid object with which to compare. 3497 6.7.4. getDER 3499 public byte[] getDER() 3501 Returns the full ASN.1 DER encoding for this oid object, which 3502 includes the tag and length. 3504 6.7.5. containedIn 3506 public boolean containedIn(Oid[] oids) 3508 A utility method to test if an Oid object is contained within the 3509 supplied Oid object array. 3511 Parameters: 3513 oids An array of oids to search. 3515 6.8. public class GSSException extends Exception 3517 This exception is thrown whenever a fatal GSS-API error occurs 3518 including mechanism-specific errors. It may contain both, the major 3519 and minor, GSS-API status codes. The mechanism implementors are 3520 responsible for setting appropriate minor status codes when throwing 3521 this exception. Aside from delivering the numeric error code(s) to 3522 the caller, this class performs the mapping from their numeric values 3523 to textual representations. This exception may also include an 3524 output token that should be sent to the peer. For example, when an 3525 initSecContext call fails due to a fatal error, the mechanism may 3526 define an error token that should be sent to the peer for debugging 3527 or informational purpose. All Java GSS-API methods are declared 3528 throwing this exception. 3530 All implementations are encouraged to use the Java 3531 internationalization techniques to provide local translations of the 3532 message strings. 3534 6.8.1. Static Constants 3536 All valid major GSS-API error code values are declared as constants 3537 in this class. 3539 public static final int BAD_BINDINGS 3541 Channel bindings mismatch error. The value of this constant is 1. 3543 public static final int BAD_MECH 3544 Unsupported mechanism requested error. The value of this constant is 3545 2. 3547 public static final int BAD_NAME 3549 Invalid name provided error. The value of this constant is 3. 3551 public static final int BAD_NAMETYPE 3553 Name of unsupported type provided error. The value of this constant 3554 is 4. 3556 public static final int BAD_STATUS 3558 Invalid status code error - this is the default status value. The 3559 value of this constant is 5. 3561 public static final int BAD_MIC 3563 Token had invalid integrity check error. The value of this constant 3564 is 6. 3566 public static final int CONTEXT_EXPIRED 3568 Specified security context expired error. The value of this constant 3569 is 7. 3571 public static final int CREDENTIALS_EXPIRED 3573 Expired credentials detected error. The value of this constant is 8. 3575 public static final int DEFECTIVE_CREDENTIAL 3577 Defective credential error. The value of this constant is 9. 3579 public static final int DEFECTIVE_TOKEN 3581 Defective token error. The value of this constant is 10. 3583 public static final int FAILURE 3585 General failure, unspecified at GSS-API level. The value of this 3586 constant is 11. 3588 public static final int NO_CONTEXT 3590 Invalid security context error. The value of this constant is 12. 3592 public static final int NO_CRED 3594 Invalid credentials error. The value of this constant is 13. 3596 public static final int BAD_QOP 3598 Unsupported QOP value error. The value of this constant is 14. 3600 public static final int UNAUTHORIZED 3602 Operation unauthorized error. The value of this constant is 15. 3604 public static final int UNAVAILABLE 3606 Operation unavailable error. The value of this constant is 16. 3608 public static final int DUPLICATE_ELEMENT 3610 Duplicate credential element requested error. The value of this 3611 constant is 17. 3613 public static final int NAME_NOT_MN 3615 Name contains multi-mechanism elements error. The value of this 3616 constant is 18. 3618 public static final int DUPLICATE_TOKEN 3620 The token was a duplicate of an earlier token. This is contained in 3621 an exception only when detected during context establishment, in 3622 which case it is considered a fatal error. (Non-fatal supplementary 3623 codes are indicated via the MessageProp object.) The value of this 3624 constant is 19. 3626 public static final int OLD_TOKEN 3628 The token's validity period has expired. This is contained in an 3629 exception only when detected during context establishment, in which 3630 case it is considered a fatal error. (Non-fatal supplementary codes 3631 are indicated via the MessageProp object.) The value of this 3632 constant is 20. 3634 public static final int UNSEQ_TOKEN 3636 A later token has already been processed. This is contained in an 3637 exception only when detected during context establishment, in which 3638 case it is considered a fatal error. (Non-fatal supplementary codes 3639 are indicated via the MessageProp object.) The value of this 3640 constant is 21. 3642 public static final int GAP_TOKEN 3644 An expected per-message token was not received. This is contained in 3645 an exception only when detected during context establishment, in 3646 which case it is considered a fatal error. (Non-fatal supplementary 3647 codes are indicated via the MessageProp object.) The value of this 3648 constant is 22. 3650 6.8.2. Constructors 3652 public GSSException(int majorCode) 3654 Creates a GSSException object with a specified major code. 3656 Calling this constructor is equivalent to calling 3657 GSSException(majorCode, null, 0, null, null). 3659 public GSSException(int majorCode, int minorCode, String minorString) 3661 Creates a GSSException object with the specified major code, minor 3662 code, and minor code textual explanation. This constructor is to be 3663 used when the exception is originating from the security mechanism. 3664 It allows to specify the GSS code and the mechanism code. 3666 Calling this constructor is equivalent to calling 3667 GSSException(majorCode, null, minorCode, minorString, null). 3669 public GSSException(int majorCode, String majorString, 3670 int minorCode, String minorString, 3671 byte[] outputToken) 3673 Creates a GSSException object with the specified major code, major 3674 code textual explanation, minor code, minor code textual explanation, 3675 and an output token. This is a general-purpose constructor that can 3676 be used to create any type of GSSException. 3678 Parameters: 3680 majorCode The GSS error code causing this exception to be 3681 thrown. 3683 majorString The textual explanation of the GSS error code. 3684 If null is provided, a default explanation that 3685 matches the majorCode will be set. 3687 minorCode The mechanism error code causing this exception 3688 to be thrown. Can be 0 if no mechanism error 3689 code is available. 3691 minorString The textual explanation of the mechanism error 3692 code. Can be null if no textual explanation is 3693 available. 3695 outputToken The output token that should be sent to the peer. 3696 Can be null if no such token is available. It 3697 must not be an empty array. When provided, the 3698 array will be cloned to protect against 3699 subsequent modifications. 3701 6.8.3. getMajor 3703 public int getMajor() 3705 Returns the major code representing the GSS error code that caused 3706 this exception to be thrown. 3708 6.8.4. getMinor 3710 public int getMinor() 3712 Returns the mechanism error code that caused this exception. The 3713 minor code is set by the underlying mechanism. Value of 0 indicates 3714 that mechanism error code is not set. 3716 6.8.5. getMajorString 3718 public String getMajorString() 3720 Returns a string explaining the GSS major error code causing this 3721 exception to be thrown. 3723 6.8.6. getMinorString 3725 public String getMinorString() 3727 Returns a string explaining the mechanism-specific error code. "null" 3728 will be returned when no string explaining the mechanism error code 3729 has been set. 3731 6.8.7. getOutputToken 3733 public byte[] getOutputToken 3735 Returns the output token in a new byte array. 3737 If the method (For example, GSSContext#initSecContext) that throws 3738 this GSSException needs to generate an output token that should be 3739 sent to the peer, that token will be stored in this GSSException and 3740 can be retrieved with this method. 3742 The return value must be null if no such token is generated. It must 3743 not be an empty byte array. 3745 6.8.8. setMinor 3747 public void setMinor(int minorCode, String message) 3749 Used internally by the GSS-API implementation and the underlying 3750 mechanisms to set the minor code and its textual representation. 3752 Parameters: 3754 minorCode The mechanism-specific error code. 3756 message A textual explanation of the mechanism error 3757 code. 3759 6.8.9. toString 3761 public String toString() 3763 Returns a textual representation of both the major and minor status 3764 codes. 3766 6.8.10. getMessage 3768 public String getMessage() 3770 Returns a detailed message of this exception. Overrides 3771 Throwable.getMessage. It is customary in Java to use this method to 3772 obtain exception information. 3774 7. Sample Applications 3775 7.1. Simple GSS Context Initiator 3777 3778 import org.ietf.jgss.*; 3780 /** 3781 * This is a partial sketch for a simple client program that acts 3782 * as a GSS context initiator. It illustrates how to use the Java 3783 * bindings for the GSS-API specified in 3784 * Generic Security Service API Version 2 : Java bindings 3785 * 3786 * 3787 * This code sketch assumes the existence of a GSS-API 3788 * implementation that supports the mechanism that it will need 3789 * and is present as a library package (org.ietf.jgss) either as 3790 * part of the standard JRE or in the CLASSPATH the application 3791 * specifies. 3792 */ 3794 public class SimpleClient { 3796 private String serviceName; // name of peer (i.e., server) 3797 private GSSCredential clientCred = null; 3798 private GSSContext context = null; 3799 private Oid mech; // underlying mechanism to use 3801 private GSSManager mgr = GSSManager.getInstance(); 3803 ... 3804 ... 3806 private void clientActions() { 3807 initializeGSS(); 3808 establishContext(); 3809 doCommunication(); 3810 } 3812 /** 3813 * Acquire credentials for the client. 3814 */ 3815 private void initializeGSS() { 3817 try { 3819 clientCred = mgr.createCredential(null /*default princ*/, 3820 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 3821 mech /* mechanism to use */, 3822 GSSCredential.INITIATE_ONLY /* init context */); 3824 print("GSSCredential created for " + 3825 cred.getName().toString()); 3826 print("Credential lifetime (sec)=" + 3827 cred.getRemainingLifetime()); 3828 } catch (GSSException e) { 3829 print("GSS-API error in credential acquisition: " 3830 + e.getMessage()); 3831 ... 3832 ... 3833 } 3834 ... 3835 ... 3836 } 3838 /** 3839 * Does the security context establishment with the 3840 * server. 3841 */ 3842 private void establishContext() { 3844 byte[] inToken = new byte[0]; 3845 byte[] outToken = null; 3847 try { 3849 GSSName peer = mgr.createName(serviceName, 3850 GSSName.NT_HOSTBASED_SERVICE); 3851 context = mgr.createContext(peer, mech, gssCred, 3852 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 3854 // Will need to support confidentiality 3855 context.requestConf(true); 3857 while (!context.isEstablished()) { 3859 outToken = context.initSecContext(inToken, 0, 3860 inToken.length); 3862 if (outToken != null) 3863 writeGSSToken(outToken); 3865 if (!context.isEstablished()) 3866 inToken = readGSSToken(); 3867 } 3869 GSSName peer = context.getSrcName(); 3870 print("Security context established with " + peer + 3871 " using underlying mechanism " + mech.toString()); 3873 } catch (GSSException e) { 3874 print("GSS-API error during context establishment: " 3875 + e.getMessage()); 3877 // If the exception contains an output token, 3878 // it should be sent to the acceptor. 3879 byte[] outTok = e.getOutputToken(); 3880 if (outTok != null) { 3881 writeGSSToken(outTok); 3882 } 3883 ... 3884 ... 3885 } 3886 ... 3887 ... 3888 } 3890 /** 3891 * Sends some data to the server and reads back the 3892 * response. 3893 */ 3894 private void doCommunication() { 3895 byte[] inToken = null; 3896 byte[] outToken = null; 3897 byte[] buffer; 3899 // Container for multiple input-output arguments to and 3900 // from the per-message routines (e.g., wrap/unwrap). 3901 MessageProp messgInfo = new MessageProp(); 3903 try { 3905 /* 3906 * Now send some bytes to the server to be 3907 * processed. They will be integrity protected 3908 * but not encrypted for privacy. 3909 */ 3911 buffer = readFromFile(); 3913 // Set privacy to "false" and use the default QOP 3914 messgInfo.setPrivacy(false); 3916 outToken = context.wrap(buffer, 0, buffer.length, 3917 messgInfo); 3919 writeGSSToken(outToken); 3920 /* 3921 * Now read the response from the server. 3922 */ 3924 inToken = readGSSToken(); 3925 buffer = context.unwrap(inToken, 0, 3926 inToken.length, messgInfo); 3927 // All ok if no exception was thrown! 3929 GSSName peer = context.getSrcName(); 3931 print("Message from " + peer.toString() 3932 + " arrived."); 3933 print("Was it encrypted? " + 3934 messgInfo.getPrivacy()); 3935 print("Duplicate Token? " + 3936 messgInfo.isDuplicateToken()); 3937 print("Old Token? " + 3938 messgInfo.isOldToken()); 3939 print("Unsequenced Token? " + 3940 messgInfo.isUnseqToken()); 3941 print("Gap Token? " + 3942 messgInfo.isGapToken()); 3943 ... 3944 ... 3945 } catch (GSSException e) { 3946 print("GSS-API error in per-message calls: " 3947 + e.getMessage()); 3948 ... 3949 ... 3950 } 3951 ... 3952 ... 3953 } // end of doCommunication method 3955 ... 3956 ... 3958 } // end of class SimpleClient 3959 3961 7.2. Simple GSS Context Acceptor 3963 3964 import org.ietf.jgss.*; 3966 /** 3967 * This is a partial sketch for a simple server program that acts 3968 * as a GSS context acceptor. It illustrates how to use the Java 3969 * bindings for the GSS-API specified in 3970 * Generic Security Service API Version 2 : Java bindings. 3971 * 3972 * This code sketch assumes the existence of a GSS-API 3973 * implementation that supports the mechanisms that it will need 3974 * and is present as a library package (org.ietf.jgss) either as 3975 * part of the standard JRE or in the CLASSPATH the application 3976 * specifies. 3977 */ 3979 import org.ietf.jgss.*; 3981 public class SimpleServer { 3983 private String serviceName; 3984 private GSSName name; 3985 private GSSCredential cred; 3987 private GSSManager mgr; 3989 ... 3990 ... 3992 /** 3993 * Wait for client connections, establish security contexts 3994 * and provide service. 3995 */ 3996 private void loop() { 3997 ... 3998 ... 3999 mgr = GSSManager.getInstance(); 4001 name = mgr.createName(serviceName, 4002 GSSName.NT_HOSTBASED_SERVICE); 4004 cred = mgr.createCredential(name, 4005 GSSCredential.INDEFINITE_LIFETIME, 4006 null, 4007 GSSCredential.ACCEPT_ONLY); 4009 // Loop infinitely 4010 while (true) { 4011 Socket s = serverSock.accept(); 4013 // Start a new thread to serve this connection 4014 Thread serverThread = new ServerThread(s); 4015 serverThread.start(); 4017 } 4018 } 4020 /** 4021 * Inner class ServerThread whose run() method provides the 4022 * secure service to a connection. 4023 */ 4025 private class ServerThread extends Thread { 4027 ... 4028 ... 4030 /** 4031 * Deals with the connection from one client. It also 4032 * handles all GSSException's thrown while talking to 4033 * this client. 4034 */ 4035 public void run() { 4037 byte[] inToken = null; 4038 byte[] outToken = null; 4039 byte[] buffer; 4041 GSSName peer; 4043 // Container for multiple input-output arguments to 4044 // and from the per-message routines 4045 // (i.e., wrap/unwrap). 4046 MessageProp supplInfo = new MessageProp(); 4047 GSSContext secContext = null; 4049 try { 4050 // Now do the context establishment loop 4051 GSSContext context = mgr.createContext(cred); 4053 while (!context.isEstablished()) { 4055 inToken = readGSSToken(); 4056 outToken = context.acceptSecContext(inToken, 4057 0, inToken.length); 4058 if (outToken != null) 4059 writeGSSToken(outToken); 4060 } 4062 // SimpleServer wants confidentiality to be 4063 // available. Check for it. 4064 if (!context.getConfState()){ 4065 ... 4066 ... 4067 } 4069 GSSName peer = context.getSrcName(); 4070 Oid mech = context.getMech(); 4071 print("Security context established with " + 4072 peer.toString() + 4073 " using underlying mechanism " + 4074 mech.toString() + 4075 " from Provider " + 4076 context.getProvider().getName()); 4078 // Now read the bytes sent by the client to be 4079 // processed. 4080 inToken = readGSSToken(); 4082 // Unwrap the message 4083 buffer = context.unwrap(inToken, 0, 4084 inToken.length, supplInfo); 4085 // All ok if no exception was thrown! 4087 // Print other supplementary per-message status 4088 // information. 4090 print("Message from " + 4091 peer.toString() + " arrived."); 4092 print("Was it encrypted? " + 4093 supplInfo.getPrivacy()); 4094 print("Duplicate Token? " + 4095 supplInfo.isDuplicateToken()); 4096 print("Old Token? " + supplInfo.isOldToken()); 4097 print("Unsequenced Token? " + 4098 supplInfo.isUnseqToken()); 4099 print("Gap Token? " + supplInfo.isGapToken()); 4101 /* 4102 * Now process the bytes and send back an 4103 * encrypted response. 4104 */ 4106 buffer = serverProcess(buffer); 4108 // Encipher it and send it across 4110 supplInfo.setPrivacy(true); // privacy requested 4111 supplInfo.setQOP(0); // default QOP 4112 outToken = context.wrap(buffer, 0, buffer.length, 4113 supplInfo); 4114 writeGSSToken(outToken); 4116 } catch (GSSException e) { 4117 print("GSS-API Error: " + e.getMessage()); 4118 // Alternatively, could call e.getMajorMessage() 4119 // and e.getMinorMessage() 4121 // If the exception contains an output token, 4122 // it should be sent to the initiator. 4123 byte[] outTok = e.getOutputToken(); 4124 if (outTok != null) { 4125 writeGSSToken(outTok); 4126 } 4127 print("Abandoning security context."); 4128 ... 4129 ... 4130 } 4131 ... 4132 ... 4133 } // end of run method in ServerThread 4135 } // end of inner class ServerThread 4137 ... 4138 ... 4140 } // end of class SimpleServer 4141 4143 8. Security Considerations 4145 The Java language security model allows platform providers to have 4146 policy-based fine-grained access control over any resource that an 4147 application wants. When using a Java security manager (such as, but 4148 not limited to, the case of applets running in browsers) the 4149 application code is in a sandbox by default. 4151 Administrators of the platform JRE determine what permissions, if 4152 any, are to be given to source from different codebases. Thus, the 4153 administrator has to be aware of any special requirements that the 4154 GSS provider might have for system resources. For instance, a 4155 Kerberos provider might wish to make a network connection to the Key 4156 Distribution Center (KDC) to obtain initial credentials. This would 4157 not be allowed under the sandbox unless the administrator had granted 4158 permissions for this. Also, note that this granting and checking of 4159 permissions happens transparently to the application and is outside 4160 the scope of this document. 4162 The Java language allows administrators to pre-configure a list of 4163 security service providers in the /lib/security/java.security 4164 file. At runtime, the system approaches these providers in order of 4165 preference when looking for security related services. Applications 4166 have a means to modify this list through methods in the "Security" 4167 class in the "java.security" package. However, since these 4168 modifications would be visible in the entire Java Virtual Machine 4169 (JVM) and thus affect all code executing in it, this operation is not 4170 available in the sandbox and requires special permissions to perform. 4171 Thus, when a GSS application has special needs that are met by a 4172 particular security provider, it has two choices: 4174 1) To install the provider on a JVM-wide basis using the 4175 java.security.Security class and then depend on the system to find 4176 the right provider automatically when the need arises. (This 4177 would require the application to be granted a "insertProvider 4178 SecurityPermission".) 4180 2) To pass an instance of the provider to the local instance of 4181 GSSManager so that only factory calls going through that 4182 GSSManager use the desired provider. (This would not require any 4183 permissions.) 4185 9. IANA Considerations 4187 This document has no actions for IANA. 4189 10. Acknowledgments 4191 This proposed API leverages earlier work performed by the IETF's CAT 4192 WG as outlined in both RFC 2743 [RFC2743] and RFC 2744 [RFC2744]. 4193 Many conceptual definitions, implementation directions, and 4194 explanations have been included from these documents. 4196 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4197 Saltz, and other members of Sun's development team for their helpful 4198 input, comments, and suggestions. 4200 We would also like to thank Joe Salowey, and Michael Smith for many 4201 insightful ideas and suggestions that have contributed to this 4202 document. 4204 11. Changes since RFC 5653 4206 This document has following changes: 4208 1) New error token embedded in GSSException 4209 There is a design flaw in the initSecContext and acceptSecContext 4210 methods of the GSSContext class defined in Generic Security 4211 Service API Version 2: Java Bindings Update [RFC5653]. 4213 The methods could either return a token (possibly null if no more 4214 tokens are needed) when the call succeeds or throw a GSSException 4215 if there is a failure, but NOT both. On the other hand, the C 4216 bindings of GSS-API [RFC2744] can return both, that is to say, a 4217 call to the GSS_Init_sec_context() function can return a major 4218 status code, and at the same time, fill in the output_token 4219 argument if there is one. 4221 Without the ability to emit an error token when there is a 4222 failure, a Java application has no mechanism to tell the other 4223 side what the error is. For example, a "reject" NegTokenResp 4224 token can never be transmitted for the SPNEGO mechanism [RFC4178]. 4226 While a Java method can never return a value and throw an 4227 exception at the same time, we can embed the error token inside 4228 the exception so that the caller has a chance to retrieve it. 4229 This update adds a new GSSException constructor to include this 4230 token inside a GSSException object, and a getOutputToken() method 4231 to retrieve the token. The specification for the initSecContext 4232 and acceptSecContext methods are updated to describe the new 4233 behavior. Various examples are also updated. 4235 New JGSS programs should make use of this new feature but it is 4236 not mandatory. A program that intends to run with both old and 4237 new GSS Java bindings can use reflection to check the availability 4238 of this new method and call it accordingly. 4240 2) Removing stream-based GSSContext methods 4242 The overloaded methods of GSSContext that use input and output 4243 streams as the means to convey authentication and per-message GSS- 4244 API tokens as described in Section 5.15 of RFC 5653 [RFC5653] are 4245 removed in this update as the wire protocol should be defined by 4246 an application and not a library. It's also impossible to 4247 implement these methods correctly when the token has no self- 4248 framing (where the end cannot be determined) or the library has no 4249 knowledge of the token format (for example, as a bridge talking to 4250 another GSS library). These methods include initSecContext 4251 (Section 7.4.5 of RFC 5653 [RFC5653]), acceptSecContext 4252 (Section 7.4.9 of RFC 5653 [RFC5653]), wrap (Section 7.4.15 of RFC 4253 5653 [RFC5653]), unwrap (Section 7.4.17 of RFC 5653 [RFC5653]), 4254 getMIC (Section 7.4.19 of RFC 5653 [RFC5653]), and verifyMIC 4255 (Section 7.4.21 of RFC 5653 [RFC5653]). 4257 12. Changes since RFC 2853 4259 This document has following changes: 4261 1) Major GSS Status Code Constant Values 4263 RFC 2853 listed all the GSS status code values in two different 4264 sections: section 4.12.1 defined numeric values for them, and 4265 section 6.8.1 defined them as static constants in the GSSException 4266 class without assigning any values. Due to an inconsistent 4267 ordering between these two sections, all of the GSS major status 4268 codes resulted in misalignment, and a subsequent disagreement 4269 between deployed implementations. 4271 This document defines the numeric values of the GSS status codes 4272 in both sections, while maintaining the original ordering from 4273 section 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status 4274 code values defined in section 4.12.1. The relevant sections in 4275 this document are sections 4.12.1 and 6.8.1. 4277 2) GSS Credential Usage Constant Values 4279 RFC 2853 section 6.3.2 defines static constants for the 4280 GSSCredential usage flags. However, the values of these constants 4281 were not defined anywhere in RFC 2853 [RFC2853]. 4283 This document defines the credential usage values in section 4284 6.3.1. The original ordering of these values from section 6.3.2 4285 of RFC 2853 [RFC2853] is maintained. 4287 3) GSS Host-Based Service Name 4289 RFC 2853 [RFC2853], section 6.2.2, defines the static constant for 4290 the GSS host-based service OID NT_HOSTBASED_SERVICE, using a 4291 deprecated OID value. 4293 This document updates the NT_HOSTBASED_SERVICE OID value in 4294 section 6.2.1 to be consistent with the C-bindings in RFC 2744 4295 [RFC2744]. 4297 13. References 4299 13.1. Normative References 4301 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism 4302 (SPKM)", RFC 2025, DOI 10.17487/RFC2025, October 1996, 4303 . 4305 [RFC2743] Linn, J., "Generic Security Service Application Program 4306 Interface Version 2, Update 1", RFC 2743, 4307 DOI 10.17487/RFC2743, January 2000, 4308 . 4310 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 4311 C-bindings", RFC 2744, DOI 10.17487/RFC2744, January 2000, 4312 . 4314 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API 4315 Version 2 : Java Bindings", RFC 2853, 4316 DOI 10.17487/RFC2853, June 2000, 4317 . 4319 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 4320 Version 5 Generic Security Service Application Program 4321 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 4322 DOI 10.17487/RFC4121, July 2005, 4323 . 4325 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The 4326 Simple and Protected Generic Security Service Application 4327 Program Interface (GSS-API) Negotiation Mechanism", 4328 RFC 4178, DOI 10.17487/RFC4178, October 2005, 4329 . 4331 [RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API 4332 Version 2: Java Bindings Update", RFC 5653, 4333 DOI 10.17487/RFC5653, August 2009, 4334 . 4336 13.2. Informative References 4338 [JLS] Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java 4339 Language Specification", Third Edition, 2005, 4340 . 4342 Authors' Addresses 4344 Mayank D. Upadhyay 4345 Google Inc. 4346 1600 Amphitheatre Parkway 4347 Mountain View, CA 94043 4348 USA 4350 Email: m.d.upadhyay+ietf@gmail.com 4351 Seema Malkani 4352 ActivIdentity Corp. 4353 6623 Dumbarton Circle 4354 Fremont, California 94555 4355 USA 4357 Email: Seema.Malkani@gmail.com 4359 Wang Weijun 4360 Oracle 4361 Building No. 24, Zhongguancun Software Park 4362 Beijing 100193 4363 China 4365 Email: weijun.wang@oracle.com