idnits 2.17.1 draft-ietf-kitten-rfc5653bis-04.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 (December 5, 2016) is 2689 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: June 8, 2017 W. Wang 7 Oracle 8 December 5, 2016 10 Generic Security Service API Version 2: Java Bindings Update 11 draft-ietf-kitten-rfc5653bis-04 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 http://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 June 8, 2017. 54 Copyright Notice 56 Copyright (c) 2016 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . 10 87 3.2. Mutual Authentication . . . . . . . . . . . . . . . . . . 10 88 3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 11 89 3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 12 90 3.5. Confidentiality . . . . . . . . . . . . . . . . . . . . . 13 91 3.6. Inter-process Context Transfer . . . . . . . . . . . . . 13 92 3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . . . . . . . . 16 99 4.6. Object Identifiers . . . . . . . . . . . . . . . . . . . 16 100 4.7. Object Identifier Sets . . . . . . . . . . . . . . . . . 16 101 4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . . 17 102 4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18 103 4.10. Authentication Tokens . . . . . . . . . . . . . . . . . . 19 104 4.11. Inter-Process Tokens . . . . . . . . . . . . . . . . . . 19 105 4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . . 20 106 4.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . 20 107 4.12.2. Mechanism-Specific Status Codes . . . . . . . . . . 22 108 4.12.3. Supplementary Status Codes . . . . . . . . . . . . . 23 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. Example Code . . . . . . . . . . . . . . . . . . . . 34 124 6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 35 125 6.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . 35 126 6.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 35 127 6.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 35 128 6.1.6. createName . . . . . . . . . . . . . . . . . . . . . 35 129 6.1.7. createName . . . . . . . . . . . . . . . . . . . . . 36 130 6.1.8. createName . . . . . . . . . . . . . . . . . . . . . 36 131 6.1.9. createName . . . . . . . . . . . . . . . . . . . . . 37 132 6.1.10. createCredential . . . . . . . . . . . . . . . . . . 38 133 6.1.11. createCredential . . . . . . . . . . . . . . . . . . 38 134 6.1.12. createCredential . . . . . . . . . . . . . . . . . . 39 135 6.1.13. createContext . . . . . . . . . . . . . . . . . . . . 39 136 6.1.14. createContext . . . . . . . . . . . . . . . . . . . . 40 137 6.1.15. createContext . . . . . . . . . . . . . . . . . . . . 40 138 6.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . 41 139 6.1.17. Example Code . . . . . . . . . . . . . . . . . . . . 41 140 6.1.18. addProviderAtEnd . . . . . . . . . . . . . . . . . . 43 141 6.1.19. Example Code . . . . . . . . . . . . . . . . . . . . 43 142 6.2. public interface GSSName . . . . . . . . . . . . . . . . 44 143 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . 44 144 6.2.2. Static Constants . . . . . . . . . . . . . . . . . . 45 145 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . 46 146 6.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . 46 147 6.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . 47 148 6.2.6. export . . . . . . . . . . . . . . . . . . . . . . . 47 149 6.2.7. toString . . . . . . . . . . . . . . . . . . . . . . 47 150 6.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 48 151 6.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 48 152 6.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . 48 153 6.3. public interface GSSCredential implements Cloneable . . . 48 154 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . 49 155 6.3.2. Static Constants . . . . . . . . . . . . . . . . . . 50 156 6.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 50 157 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 50 158 6.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 50 159 6.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . 51 160 6.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . 51 161 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . 51 162 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 163 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 164 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 52 165 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 52 166 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 53 167 6.4. public interface GSSContext . . . . . . . . . . . . . . . 54 168 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 55 169 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . 56 170 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . 57 171 6.4.4. Example Code . . . . . . . . . . . . . . . . . . . . 57 172 6.4.5. acceptSecContext . . . . . . . . . . . . . . . . . . 58 173 6.4.6. Example Code . . . . . . . . . . . . . . . . . . . . 59 174 6.4.7. isEstablished . . . . . . . . . . . . . . . . . . . . 60 175 6.4.8. dispose . . . . . . . . . . . . . . . . . . . . . . . 61 176 6.4.9. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 61 177 6.4.10. wrap . . . . . . . . . . . . . . . . . . . . . . . . 62 178 6.4.11. unwrap . . . . . . . . . . . . . . . . . . . . . . . 63 179 6.4.12. getMIC . . . . . . . . . . . . . . . . . . . . . . . 63 180 6.4.13. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 64 181 6.4.14. export . . . . . . . . . . . . . . . . . . . . . . . 65 182 6.4.15. requestMutualAuth . . . . . . . . . . . . . . . . . . 66 183 6.4.16. requestReplayDet . . . . . . . . . . . . . . . . . . 66 184 6.4.17. requestSequenceDet . . . . . . . . . . . . . . . . . 66 185 6.4.18. requestCredDeleg . . . . . . . . . . . . . . . . . . 66 186 6.4.19. requestAnonymity . . . . . . . . . . . . . . . . . . 67 187 6.4.20. requestConf . . . . . . . . . . . . . . . . . . . . . 67 188 6.4.21. requestInteg . . . . . . . . . . . . . . . . . . . . 67 189 6.4.22. requestLifetime . . . . . . . . . . . . . . . . . . . 68 190 6.4.23. setChannelBinding . . . . . . . . . . . . . . . . . . 68 191 6.4.24. getCredDelegState . . . . . . . . . . . . . . . . . . 68 192 6.4.25. getMutualAuthState . . . . . . . . . . . . . . . . . 68 193 6.4.26. getReplayDetState . . . . . . . . . . . . . . . . . . 69 194 6.4.27. getSequenceDetState . . . . . . . . . . . . . . . . . 69 195 6.4.28. getAnonymityState . . . . . . . . . . . . . . . . . . 69 196 6.4.29. isTransferable . . . . . . . . . . . . . . . . . . . 69 197 6.4.30. isProtReady . . . . . . . . . . . . . . . . . . . . . 69 198 6.4.31. getConfState . . . . . . . . . . . . . . . . . . . . 70 199 6.4.32. getIntegState . . . . . . . . . . . . . . . . . . . . 70 200 6.4.33. getLifetime . . . . . . . . . . . . . . . . . . . . . 70 201 6.4.34. getSrcName . . . . . . . . . . . . . . . . . . . . . 70 202 6.4.35. getTargName . . . . . . . . . . . . . . . . . . . . . 70 203 6.4.36. getMech . . . . . . . . . . . . . . . . . . . . . . . 70 204 6.4.37. getDelegCred . . . . . . . . . . . . . . . . . . . . 71 205 6.4.38. isInitiator . . . . . . . . . . . . . . . . . . . . . 71 206 6.5. public class MessageProp . . . . . . . . . . . . . . . . 71 207 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 71 208 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 72 209 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 72 210 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 72 211 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 72 212 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 72 213 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 73 214 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 73 215 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 73 216 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 73 217 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 73 218 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 73 219 6.6. public class ChannelBinding . . . . . . . . . . . . . . . 74 220 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 74 221 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 75 222 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 75 223 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . 75 224 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 76 225 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 76 226 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 76 227 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 77 228 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 77 229 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 77 230 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 77 231 6.8. public class GSSException extends Exception . . . . . . . 78 232 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . 78 233 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 81 234 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 82 235 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 82 236 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 82 237 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 82 238 6.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 82 239 6.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 83 240 6.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 83 241 6.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 83 242 7. Sample Applications . . . . . . . . . . . . . . . . . . . . . 83 243 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 83 244 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 87 245 8. Security Considerations . . . . . . . . . . . . . . . . . . . 91 246 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 92 247 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 92 248 11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 92 249 12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 93 250 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 94 251 13.1. Normative References . . . . . . . . . . . . . . . . . . 94 252 13.2. Informative References . . . . . . . . . . . . . . . . . 95 253 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 95 255 1. Introduction 257 This document specifies Java language bindings for the Generic 258 Security Services Application Programming Interface version 2 (GSS- 259 API). GSS-API version 2 is described in a language-independent 260 format in RFC 2743 [RFC2743]. The GSS-API allows a caller 261 application to authenticate a principal identity, to delegate rights 262 to a peer, and to apply security services such as confidentiality and 263 integrity on a per-message basis. 265 This document and its predecessor, RFC 2853 [RFC2853] and RFC 5653 266 [RFC5653], leverage the work done by the working group (WG) in the 267 area of RFC 2743 [RFC2743] and the C-bindings of RFC 2744 [RFC2744]. 268 Whenever appropriate, text has been used from the C-bindings document 269 (RFC 2744) to explain generic concepts and provide direction to the 270 implementors. 272 The design goals of this API have been to satisfy all the 273 functionality defined in RFC 2743 [RFC2743] and to provide these 274 services in an object-oriented method. The specification also aims 275 to satisfy the needs of both types of Java application developers, 276 those who would like access to a "system-wide" GSS-API 277 implementation, as well as those who would want to provide their own 278 "custom" implementation. 280 A system-wide implementation is one that is available to all 281 applications in the form of a library package. It may be the 282 standard package in the Java runtime environment (JRE) being used or 283 it may be additionally installed and accessible to any application 284 via the CLASSPATH. 286 A custom implementation of the GSS-API, on the other hand, is one 287 that would, in most cases, be bundled with the application during 288 distribution. It is expected that such an implementation would be 289 meant to provide for some particular need of the application, such as 290 support for some specific mechanism. 292 The design of this API also aims to provide a flexible framework to 293 add and manage GSS-API mechanisms. GSS-API leverages the Java 294 Cryptography Architecture (JCA) provider model to support the 295 plugability of mechanisms. Mechanisms can be added on a system-wide 296 basis, where all users of the framework will have them available. 297 The specification also allows for the addition of mechanisms per- 298 instance of the GSS-API. 300 Lastly, this specification presents an API that will naturally fit 301 within the operation environment of the Java platform. Readers are 302 assumed to be familiar with both the GSS-API and the Java platform. 304 2. GSS-API Operational Paradigm 306 "Generic Security Service Application Programming Interface, Version 307 2" [RFC2743] defines a generic security API to calling applications. 308 It allows a communicating application to authenticate the user 309 associated with another application, to delegate rights to another 310 application, and to apply security services such as confidentiality 311 and integrity on a per-message basis. 313 There are four stages to using GSS-API: 315 1) The application acquires a set of credentials with which it may 316 prove its identity to other processes. The application's 317 credentials vouch for its global identity, which may or may not be 318 related to any local username under which it may be running. 320 2) A pair of communicating applications establish a joint security 321 context using their credentials. The security context 322 encapsulates shared state information, which is required in order 323 that per-message security services may be provided. Examples of 324 state information that might be shared between applications as 325 part of a security context are cryptographic keys and message 326 sequence numbers. As part of the establishment of a security 327 context, the context initiator is authenticated to the responder, 328 and may require that the responder is authenticated back to the 329 initiator. The initiator may optionally give the responder the 330 right to initiate further security contexts, acting as an agent or 331 delegate of the initiator. This transfer of rights is termed 332 "delegation", and is achieved by creating a set of credentials, 333 similar to those used by the initiating application, but which may 334 be used by the responder. 336 A GSSContext object is used to establish and maintain the shared 337 information that makes up the security context. Certain 338 GSSContext methods will generate a token, which applications treat 339 as cryptographically protected, opaque data. The caller of such a 340 GSSContext method is responsible for transferring the token to the 341 peer application, encapsulated if necessary in an application-to- 342 application protocol. On receipt of such a token, the peer 343 application should pass it to a corresponding GSSContext method 344 which will decode the token and extract the information, updating 345 the security context state information accordingly. 347 3) Per-message services are invoked on a GSSContext object to apply 348 either: 350 integrity and data origin authentication, or 352 confidentiality, integrity and data origin authentication 354 to application data, which are treated by GSS-API as arbitrary 355 octet-strings. An application transmitting a message that it 356 wishes to protect will call the appropriate GSSContext method 357 (getMIC or wrap) to apply protection, and send the resulting token 358 to the receiving application. The receiver will pass the received 359 token (and, in the case of data protected by getMIC, the 360 accompanying message-data) to the corresponding decoding method of 361 the GSSContext interface (verifyMIC or unwrap) to remove the 362 protection and validate the data. 364 4) At the completion of a communications session (which may extend 365 across several transport connections), each application uses a 366 GSSContext method to invalidate the security context and release 367 any system or cryptographic resources held. Multiple contexts may 368 also be used (either successively or simultaneously) within a 369 single communications association, at the discretion of the 370 applications. 372 3. Additional Controls 374 This section discusses the optional services that a context initiator 375 may request of the GSS-API before the context establishment. Each of 376 these services is requested by calling the appropriate mutator method 377 in the GSSContext object before the first call to init is performed. 378 Only the context initiator can request context flags. 380 The optional services defined are: 382 Delegation: The (usually temporary) transfer of rights from 383 initiator to acceptor, enabling the acceptor to authenticate 384 itself as an agent of the initiator. 386 Mutual Authentication: In addition to the initiator authenticating 387 its identity to the context acceptor, the context acceptor should 388 also authenticate itself to the initiator. 390 Replay Detection: In addition to providing message integrity 391 services, GSSContext per-message operations of getMIC and wrap 392 should include message numbering information to enable verifyMIC 393 and unwrap to detect if a message has been duplicated. 395 Out-of-Sequence Detection: In addition to providing message 396 integrity services, GSSContext per-message operations (getMIC and 397 wrap) should include message sequencing information to enable 398 verifyMIC and unwrap to detect if a message has been received out 399 of sequence. 401 Anonymous Authentication: The establishment of the security 402 context should not reveal the initiator's identity to the context 403 acceptor. 405 Some mechanisms may not support all optional services, and some 406 mechanisms may only support some services in conjunction with others. 407 The GSSContext interface offers query methods to allow the 408 verification by the calling application of which services will be 409 available from the context when the establishment phase is complete. 410 In general, if the security mechanism is capable of providing a 411 requested service, it should do so even if additional services must 412 be enabled in order to provide the requested service. If the 413 mechanism is incapable of providing a requested service, it should 414 proceed without the service leaving the application to abort the 415 context establishment process if it considers the requested service 416 to be mandatory. 418 Some mechanisms may specify that support for some services is 419 optional, and that implementors of the mechanism need not provide it. 420 This is most commonly true of the confidentiality service, often 421 because of legal restrictions on the use of data-encryption, but may 422 apply to any of the services. Such mechanisms are required to send 423 at least one token from acceptor to initiator during context 424 establishment when the initiator indicates a desire to use such a 425 service, so that the initiating GSS-API can correctly indicate 426 whether the service is supported by the acceptor's GSS-API. 428 3.1. Delegation 430 The GSS-API allows delegation to be controlled by the initiating 431 application via the requestCredDeleg method before the first call to 432 init has been issued. Some mechanisms do not support delegation, and 433 for such mechanisms, attempts by an application to enable delegation 434 are ignored. 436 The acceptor of a security context, for which the initiator enabled 437 delegation, can check if delegation was enabled by using the 438 getCredDelegState method of the GSSContext interface. In cases when 439 it is enabled, the delegated credential object can be obtained by 440 calling the getDelegCred method. The obtained GSSCredential object 441 may then be used to initiate subsequent GSS-API security contexts as 442 an agent or delegate of the initiator. If the original initiator's 443 identity is "A" and the delegate's identity is "B", then, depending 444 on the underlying mechanism, the identity embodied by the delegated 445 credential may be either "A" or "B acting for A". 447 For many mechanisms that support delegation, a simple boolean does 448 not provide enough control. Examples of additional aspects of 449 delegation control that a mechanism might provide to an application 450 are duration of delegation, network addresses from which delegation 451 is valid, and constraints on the tasks that may be performed by a 452 delegate. Such controls are presently outside the scope of the GSS- 453 API. GSS-API implementations supporting mechanisms offering 454 additional controls should provide extension routines that allow 455 these controls to be exercised (perhaps by modifying the initiator's 456 GSS-API credential object prior to its use in establishing a 457 context). However, the simple delegation control provided by GSS-API 458 should always be able to override other mechanism-specific delegation 459 controls. If the application instructs the GSSContext object that 460 delegation is not desired, then the implementation must not permit 461 delegation to occur. This is an exception to the general rule that a 462 mechanism may enable services even if they are not requested -- 463 delegation may only be provided at the explicit request of the 464 application. 466 3.2. Mutual Authentication 468 Usually, a context acceptor will require that a context initiator 469 authenticate itself so that the acceptor may make an access-control 470 decision prior to performing a service for the initiator. In some 471 cases, the initiator may also request that the acceptor authenticate 472 itself. GSS-API allows the initiating application to request this 473 mutual authentication service by calling the requestMutualAuth method 474 of the GSSContext interface with a "true" parameter before making the 475 first call to init. The initiating application is informed as to 476 whether or not the context acceptor has authenticated itself. Note 477 that some mechanisms may not support mutual authentication, and other 478 mechanisms may always perform mutual authentication, whether or not 479 the initiating application requests it. In particular, mutual 480 authentication may be required by some mechanisms in order to support 481 replay or out-of-sequence message detection, and for such mechanisms, 482 a request for either of these services will automatically enable 483 mutual authentication. 485 3.3. Replay and Out-of-Sequence Detection 487 The GSS-API may provide detection of mis-ordered messages once a 488 security context has been established. Protection may be applied to 489 messages by either application, by calling either getMIC or wrap 490 methods of the GSSContext interface, and verified by the peer 491 application by calling verifyMIC or unwrap for the peer's GSSContext 492 object. 494 The getMIC method calculates a cryptographic checksum of an 495 application message, and returns that checksum in a token. The 496 application should pass both the token and the message to the peer 497 application, which presents them to the verifyMIC method of the 498 peer's GSSContext object. 500 The wrap method calculates a cryptographic checksum of an application 501 message, and places both the checksum and the message inside a single 502 token. The application should pass the token to the peer 503 application, which presents it to the unwrap method of the peer's 504 GSSContext object to extract the message and verify the checksum. 506 Either pair of routines may be capable of detecting out-of-sequence 507 message delivery or the duplication of messages. Details of such 508 mis-ordered messages are indicated through supplementary query 509 methods of the MessageProp object that is filled in by each of these 510 routines. 512 A mechanism need not maintain a list of all tokens that have been 513 processed in order to support these status codes. A typical 514 mechanism might retain information about only the most recent "N" 515 tokens processed, allowing it to distinguish duplicates and missing 516 tokens within the most recent "N" messages; the receipt of a token 517 older than the most recent "N" would result in the isOldToken method 518 of the instance of MessageProp to return "true". 520 3.4. Anonymous Authentication 522 In certain situations, an application may wish to initiate the 523 authentication process to authenticate a peer, without revealing its 524 own identity. As an example, consider an application providing 525 access to a database containing medical information and offering 526 unrestricted access to the service. A client of such a service might 527 wish to authenticate the service (in order to establish trust in any 528 information retrieved from it), but might not wish the service to be 529 able to obtain the client's identity (perhaps due to privacy concerns 530 about the specific inquiries, or perhaps simply to avoid being placed 531 on mailing-lists). 533 In normal use of the GSS-API, the initiator's identity is made 534 available to the acceptor as a result of the context establishment 535 process. However, context initiators may request that their identity 536 not be revealed to the context acceptor. Many mechanisms do not 537 support anonymous authentication, and for such mechanisms, the 538 request will not be honored. An authentication token will still be 539 generated, but the application is always informed if a requested 540 service is unavailable, and has the option to abort context 541 establishment if anonymity is valued above the other security 542 services that would require a context to be established. 544 In addition to informing the application that a context is 545 established anonymously (via the isAnonymous method of the GSSContext 546 class), the getSrcName method of the acceptor's GSSContext object 547 will, for such contexts, return a reserved internal-form name, 548 defined by the implementation. 550 The toString method for a GSSName object representing an anonymous 551 entity will return a printable name. The returned value will be 552 syntactically distinguishable from any valid principal name supported 553 by the implementation. The associated name-type object identifier 554 will be an oid representing the value of NT_ANONYMOUS. This name- 555 type oid will be defined as a public, static Oid object of the 556 GSSName class. The printable form of an anonymous name should be 557 chosen such that it implies anonymity, since this name may appear in, 558 for example, audit logs. For example, the string "" might 559 be a good choice, if no valid printable names supported by the 560 implementation can begin with "<" and end with ">". 562 When using the equal method of the GSSName interface, and one of the 563 operands is a GSSName instance representing an anonymous entity, the 564 method must return "false". 566 3.5. Confidentiality 568 If a GSSContext supports the confidentiality service, wrap method may 569 be used to encrypt application messages. Messages are selectively 570 encrypted, under the control of the setPrivacy method of the 571 MessageProp object used in the wrap method. 573 3.6. Inter-process Context Transfer 575 GSS-APIv2 provides functionality that allows a security context to be 576 transferred between processes on a single machine. These are 577 implemented using the export method of GSSContext and a byte array 578 constructor of the same class. The most common use for such a 579 feature is a client-server design where the server is implemented as 580 a single process that accepts incoming security contexts, which then 581 launches child processes to deal with the data on these contexts. In 582 such a design, the child processes must have access to the security 583 context object created within the parent so that they can use per- 584 message protection services and delete the security context when the 585 communication session ends. 587 Since the security context data structure is expected to contain 588 sequencing information, it is impractical in general to share a 589 context between processes. Thus, the GSSContext interface provides 590 an export method that the process, which currently owns the context, 591 can call to declare that it has no intention to use the context 592 subsequently, and to create an inter-process token containing 593 information needed by the adopting process to successfully recreate 594 the context. After successful completion of export, the original 595 security context is made inaccessible to the calling process by GSS- 596 API, and any further usage of this object will result in failures. 597 The originating process transfers the inter-process token to the 598 adopting process, which creates a new GSSContext object using the 599 byte array constructor. The properties of the context are equivalent 600 to that of the original context. 602 The inter-process token may contain sensitive data from the original 603 security context (including cryptographic keys). Applications using 604 inter-process tokens to transfer security contexts must take 605 appropriate steps to protect these tokens in transit. 607 Implementations are not required to support the inter-process 608 transfer of security contexts. Calling the isTransferable method of 609 the GSSContext interface will indicate if the context object is 610 transferable. 612 3.7. The Use of Incomplete Contexts 614 Some mechanisms may allow the per-message services to be used before 615 the context establishment process is complete. For example, a 616 mechanism may include sufficient information in its initial context- 617 level tokens for the context acceptor to immediately decode messages 618 protected with wrap or getMIC. For such a mechanism, the initiating 619 application need not wait until subsequent context-level tokens have 620 been sent and received before invoking the per-message protection 621 services. 623 An application can invoke the isProtReady method of the GSSContext 624 class to determine if the per-message services are available in 625 advance of complete context establishment. Applications wishing to 626 use per-message protection services on partially established contexts 627 should query this method before attempting to invoke wrap or getMIC. 629 4. Calling Conventions 631 Java provides the implementors with not just a syntax for the 632 language, but also an operational environment. For example, memory 633 is automatically managed and does not require application 634 intervention. These language features have allowed for a simpler API 635 and have led to the elimination of certain GSS-API functions. 637 Moreover, the JCA defines a provider model that allows for 638 implementation-independent access to security services. Using this 639 model, applications can seamlessly switch between different 640 implementations and dynamically add new services. The GSS-API 641 specification leverages these concepts by the usage of providers for 642 the mechanism implementations. 644 4.1. Package Name 646 The classes and interfaces defined in this document reside in the 647 package called "org.ietf.jgss". Applications that wish to make use 648 of this API should import this package name as shown in section 7. 650 4.2. Provider Framework 652 The Java security API's use a provider architecture that allows 653 applications to be implementation independent and security API 654 implementations to be modular and extensible. The 655 java.security.Provider class is an abstract class that a vendor 656 extends. This class maps various properties that represent different 657 security services that are available to the names of the actual 658 vendor classes that implement those services. When requesting a 659 service, an application simply specifies the desired provider and the 660 API delegates the request to service classes available from that 661 provider. 663 Using the Java security provider model insulates applications from 664 implementation details of the services they wish to use. 665 Applications can switch between providers easily and new providers 666 can be added as needed, even at runtime. 668 The GSS-API may use providers to find components for specific 669 underlying security mechanisms. For instance, a particular provider 670 might contain components that will allow the GSS-API to support the 671 Kerberos v5 mechanism [RFC4121] and another might contain components 672 to support the Simple Public-Key GSS-API Mechanism (SPKM) [RFC2025]. 673 By delegating mechanism-specific functionality to the components 674 obtained from providers, the GSS-API can be extended to support an 675 arbitrary list of mechanism. 677 How the GSS-API locates and queries these providers is beyond the 678 scope of this document and is being deferred to a Service Provider 679 Interface (SPI) specification. The availability of such an SPI 680 specification is not mandatory for the adoption of this API 681 specification nor is it mandatory to use providers in the 682 implementation of a GSS-API framework. However, by using the 683 provider framework together with an SPI specification, one can create 684 an extensible and implementation-independent GSS-API framework. 686 4.3. Integer Types 688 All numeric values are declared as "int" primitive Java type. The 689 Java specification guarantees that this will be a 32-bit two's 690 complement signed number. 692 Throughout this API, the "boolean" primitive Java type is used 693 wherever a boolean value is required or returned. 695 4.4. Opaque Data Types 697 Java byte arrays are used to represent opaque data types that are 698 consumed and produced by the GSS-API in the form of tokens. Java 699 arrays contain a length field that enables the users to easily 700 determine their size. The language has automatic garbage collection 701 that alleviates the need by developers to release memory and 702 simplifies buffer ownership issues. 704 4.5. Strings 706 The String object will be used to represent all textual data. The 707 Java String object transparently treats all characters as two-byte 708 Unicode characters, which allows support for many locals. All 709 routines returning or accepting textual data will use the String 710 object. 712 4.6. Object Identifiers 714 An Oid object will be used to represent Universal Object Identifiers 715 (Oids). Oids are ISO-defined, hierarchically globally interpretable 716 identifiers used within the GSS-API framework to identify security 717 mechanisms and name formats. The Oid object can be created from a 718 string representation of its dot notation (e.g., "1.3.6.1.5.6.2") as 719 well as from its ASN.1 DER encoding. Methods are also provided to 720 test equality and provide the DER representation for the object. 722 An important feature of the Oid class is that its instances are 723 immutable -- i.e., there are no methods defined that allow one to 724 change the contents of an Oid. This property allows one to treat 725 these objects as "statics" without the need to perform copies. 727 Certain routines allow the usage of a default oid. A "null" value 728 can be used in those cases. 730 4.7. Object Identifier Sets 732 The Java bindings represent object identifier sets as arrays of Oid 733 objects. All Java arrays contain a length field, which allows for 734 easy manipulation and reference. 736 In order to support the full functionality of RFC 2743 [RFC2743], the 737 Oid class includes a method that checks for existence of an Oid 738 object within a specified array. This is equivalent in functionality 739 to gss_test_oid_set_member. The use of Java arrays and Java's 740 automatic garbage collection has eliminated the need for the 741 following routines: gss_create_empty_oid_set, gss_release_oid_set, 742 and gss_add_oid_set_member. Java GSS-API implementations will not 743 contain them. Java's automatic garbage collection and the immutable 744 property of the Oid object eliminates the memory management issues of 745 the C counterpart. 747 Whenever a default value for an Object Identifier Set is required, a 748 "null" value can be used. Please consult the detailed method 749 description for details. 751 4.8. Credentials 753 GSS-API credentials are represented by the GSSCredential interface. 754 The interface contains several constructs to allow for the creation 755 of most common credential objects for the initiator and the acceptor. 756 Comparisons are performed using the interface's "equals" method. The 757 following general description of GSS-API credentials is included from 758 the C-bindings specification: 760 GSS-API credentials can contain mechanism-specific principal 761 authentication data for multiple mechanisms. A GSS-API credential 762 is composed of a set of credential-elements, each of which is 763 applicable to a single mechanism. A credential may contain at 764 most one credential-element for each supported mechanism. A 765 credential-element identifies the data needed by a single 766 mechanism to authenticate a single principal, and conceptually 767 contains two credential-references that describe the actual 768 mechanism-specific authentication data, one to be used by GSS-API 769 for initiating contexts, and one to be used for accepting 770 contexts. For mechanisms that do not distinguish between acceptor 771 and initiator credentials, both references would point to the same 772 underlying mechanism-specific authentication data. 774 Credentials describe a set of mechanism-specific principals, and give 775 their holder the ability to act as any of those principals. All 776 principal identities asserted by a single GSS-API credential should 777 belong to the same entity, although enforcement of this property is 778 an implementation-specific matter. A single GSSCredential object 779 represents all the credential elements that have been acquired. 781 The creation of an GSSContext object allows the value of "null" to be 782 specified as the GSSCredential input parameter. This will indicate a 783 desire by the application to act as a default principal. While 784 individual GSS-API implementations are free to determine such default 785 behavior as appropriate to the mechanism, the following default 786 behavior by these routines is recommended for portability: 788 For the initiator side of the context: 790 1) If there is only a single principal capable of initiating security 791 contexts for the chosen mechanism that the application is 792 authorized to act on behalf of, then that principal shall be used; 793 otherwise, 795 2) If the platform maintains a concept of a default network-identity 796 for the chosen mechanism, and if the application is authorized to 797 act on behalf of that identity for the purpose of initiating 798 security contexts, then the principal corresponding to that 799 identity shall be used; otherwise, 801 3) If the platform maintains a concept of a default local identity, 802 and provides a means to map local identities into network- 803 identities for the chosen mechanism, and if the application is 804 authorized to act on behalf of the network-identity image of the 805 default local identity for the purpose of initiating security 806 contexts using the chosen mechanism, then the principal 807 corresponding to that identity shall be used; otherwise, 809 4) A user-configurable default identity should be used. 811 For the acceptor side of the context: 813 1) If there is only a single authorized principal identity capable of 814 accepting security contexts for the chosen mechanism, then that 815 principal shall be used; otherwise, 817 2) If the mechanism can determine the identity of the target 818 principal by examining the context-establishment token processed 819 during the accept method, and if the accepting application is 820 authorized to act as that principal for the purpose of accepting 821 security contexts using the chosen mechanism, then that principal 822 identity shall be used; otherwise, 824 3) If the mechanism supports context acceptance by any principal, and 825 if mutual authentication was not requested, any principal that the 826 application is authorized to accept security contexts under using 827 the chosen mechanism may be used; otherwise, 829 4) A user-configurable default identity shall be used. 831 The purpose of the above rules is to allow security contexts to be 832 established by both initiator and acceptor using the default behavior 833 whenever possible. Applications requesting default behavior are 834 likely to be more portable across mechanisms and implementations than 835 ones that instantiate an GSSCredential object representing a specific 836 identity. 838 4.9. Contexts 840 The GSSContext interface is used to represent one end of a GSS-API 841 security context, storing state information appropriate to that end 842 of the peer communication, including cryptographic state information. 843 The instantiation of the context object is done differently by the 844 initiator and the acceptor. After the context has been instantiated, 845 the initiator may choose to set various context options that will 846 determine the characteristics of the desired security context. When 847 all the application-desired characteristics have been set, the 848 initiator will call the initSecContext method, which will produce a 849 token for consumption by the peer's acceptSecContext method. It is 850 the responsibility of the application to deliver the authentication 851 token(s) between the peer applications for processing. Upon 852 completion of the context-establishment phase, context attributes can 853 be retrieved, by both the initiator and acceptor, using the accessor 854 methods. These will reflect the actual attributes of the established 855 context. At this point, the context can be used by the application 856 to apply cryptographic services to its data. 858 4.10. Authentication Tokens 860 A token is a caller-opaque type that GSS-API uses to maintain 861 synchronization between each end of the GSS-API security context. 862 The token is a cryptographically protected octet-string, generated by 863 the underlying mechanism at one end of a GSS-API security context for 864 use by the peer mechanism at the other end. Encapsulation (if 865 required) within the application protocol and transfer of the token 866 are the responsibility of the peer applications. 868 Java GSS-API uses byte arrays to represent authentication tokens. 870 4.11. Inter-Process Tokens 872 Certain GSS-API routines are intended to transfer data between 873 processes in multi-process programs. These routines use a caller- 874 opaque octet-string, generated by the GSS-API in one process for use 875 by the GSS-API in another process. The calling application is 876 responsible for transferring such tokens between processes. Note 877 that, while GSS-API implementors are encouraged to avoid placing 878 sensitive information within inter-process tokens, or to 879 cryptographically protect them, many implementations will be unable 880 to avoid placing key material or other sensitive data within them. 881 It is the application's responsibility to ensure that inter-process 882 tokens are protected in transit, and transferred only to processes 883 that are trustworthy. An inter-process token is represented using a 884 byte array emitted from the export method of the GSSContext 885 interface. The receiver of the inter-process token would initialize 886 an GSSContext object with this token to create a new context. Once a 887 context has been exported, the GSSContext object is invalidated and 888 is no longer available. 890 4.12. Error Reporting 892 RFC 2743 [RFC2743] defined the usage of major and minor status values 893 for the signaling of GSS-API errors. The major code, also called GSS 894 status code, is used to signal errors at the GSS-API level, 895 independent of the underlying mechanism(s). The minor status value 896 or Mechanism status code, is a mechanism-defined error value 897 indicating a mechanism-specific error code. 899 Java GSS-API uses exceptions implemented by the GSSException class to 900 signal both minor and major error values. Both mechanism-specific 901 errors and GSS-API level errors are signaled through instances of 902 this class. The usage of exceptions replaces the need for major and 903 minor codes to be used within the API calls. The GSSException class 904 also contains methods to obtain textual representations for both the 905 major and minor values, which is equivalent to the functionality of 906 gss_display_status. A GSSException object may also include an output 907 token that should be sent to the peer. 909 4.12.1. GSS Status Codes 911 GSS status codes indicate errors that are independent of the 912 underlying mechanism(s) used to provide the security service. The 913 errors that can be indicated via a GSS status code are generic API 914 routine errors (errors that are defined in the GSS-API 915 specification). These bindings take advantage of the Java exceptions 916 mechanism, thus, eliminating the need for calling errors. 918 A GSS status code indicates a single fatal generic API error from the 919 routine that has thrown the GSSException. Using exceptions announces 920 that a fatal error has occurred during the execution of the method. 921 The GSS-API operational model also allows for the signaling of 922 supplementary status information from the per-message calls. These 923 need to be handled as return values since using exceptions is not 924 appropriate for informatory or warning-like information. The methods 925 that are capable of producing supplementary information are the two 926 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 927 These methods fill the supplementary status codes in the MessageProp 928 object that was passed in. 930 A GSSException object, along with providing the functionality for 931 setting of the various error codes and translating them into textual 932 representation, also contains the definitions of all the numeric 933 error values. The following table lists the definitions of error 934 codes: 936 Table: GSS Status Codes 937 +----------------------+-------+------------------------------------+ 938 | Name | Value | Meaning | 939 +----------------------+-------+------------------------------------+ 940 | BAD_BINDINGS | 1 | Incorrect channel bindings were | 941 | | | supplied. | 942 | | | | 943 | BAD_MECH | 2 | An unsupported mechanism was | 944 | | | requested. | 945 | | | | 946 | BAD_NAME | 3 | An invalid name was supplied. | 947 | | | | 948 | BAD_NAMETYPE | 4 | A supplied name was of an | 949 | | | unsupported type. | 950 | | | | 951 | BAD_STATUS | 5 | An invalid status code was | 952 | | | supplied. | 953 | | | | 954 | BAD_MIC | 6 | A token had an invalid MIC. | 955 | | | | 956 | CONTEXT_EXPIRED | 7 | The context has expired. | 957 | | | | 958 | CREDENTIALS_EXPIRED | 8 | The referenced credentials have | 959 | | | expired. | 960 | | | | 961 | DEFECTIVE_CREDENTIAL | 9 | A supplied credential was invalid. | 962 | | | | 963 | DEFECTIVE_TOKEN | 10 | A supplied token was invalid. | 964 | | | | 965 | FAILURE | 11 | Miscellaneous failure, unspecified | 966 | | | at the GSS-API level. | 967 | | | | 968 | NO_CONTEXT | 12 | Invalid context has been supplied. | 969 | | | | 970 | NO_CRED | 13 | No credentials were supplied, or | 971 | | | the credentials were unavailable | 972 | | | or inaccessible. | 973 | | | | 974 | BAD_QOP | 14 | The quality-of-protection (QOP) | 975 | | | requested could not be provided. | 976 | | | | 977 | UNAUTHORIZED | 15 | The operation is forbidden by the | 978 | | | local security policy. | 979 | | | | 980 | UNAVAILABLE | 16 | The operation or option is | 981 | | | unavailable. | 982 | | | | 983 | DUPLICATE_ELEMENT | 17 | The requested credential element | 984 | | | already exists. | 985 | | | | 986 | NAME_NOT_MN | 18 | The provided name was not a | 987 | | | mechanism name. | 988 +----------------------+-------+------------------------------------+ 990 The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN, 991 UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException only if 992 detected during context establishment, in which case it is a fatal 993 error. (During per-message calls, these values are indicated as 994 supplementary information contained in the MessageProp object.) They 995 are: 997 +-----------------+-------+-----------------------------------------+ 998 | Name | Value | Meaning | 999 +-----------------+-------+-----------------------------------------+ 1000 | DUPLICATE_TOKEN | 19 | The token was a duplicate of an earlier | 1001 | | | version. | 1002 | | | | 1003 | OLD_TOKEN | 20 | The token's validity period has | 1004 | | | expired. | 1005 | | | | 1006 | UNSEQ_TOKEN | 21 | A later token has already been | 1007 | | | processed. | 1008 | | | | 1009 | GAP_TOKEN | 22 | The expected token was not received. | 1010 +-----------------+-------+-----------------------------------------+ 1012 The GSS major status code of FAILURE is used to indicate that the 1013 underlying mechanism detected an error for which no specific GSS 1014 status code is defined. The mechanism-specific status code can 1015 provide more details about the error. 1017 The different major status codes that can be contained in the 1018 GSSException object thrown by the methods in this specification are 1019 the same as the major status codes returned by the corresponding 1020 calls in RFC 2743 [RFC2743]. 1022 4.12.2. Mechanism-Specific Status Codes 1024 Mechanism-specific status codes are communicated in two ways, they 1025 are part of any GSSException thrown from the mechanism-specific layer 1026 to signal a fatal error, or they are part of the MessageProp object 1027 that the per-message calls use to signal non-fatal errors. 1029 A default value of 0 in either the GSSException object or the 1030 MessageProp object will be used to represent the absence of any 1031 mechanism-specific status code. 1033 4.12.3. Supplementary Status Codes 1035 Supplementary status codes are confined to the per-message methods of 1036 the GSSContext interface. Because of the informative nature of these 1037 errors it is not appropriate to use exceptions to signal them. 1038 Instead, the per-message operations of the GSSContext interface 1039 return these values in a MessageProp object. 1041 The MessageProp class defines query methods that return boolean 1042 values indicating the following supplementary states: 1044 Table: Supplementary Status Methods 1046 +------------------+------------------------------------------------+ 1047 | Method Name | Meaning when "true" is returned | 1048 +------------------+------------------------------------------------+ 1049 | isDuplicateToken | The token was a duplicate of an earlier token. | 1050 | | | 1051 | isOldToken | The token's validity period has expired. | 1052 | | | 1053 | isUnseqToken | A later token has already been processed. | 1054 | | | 1055 | isGapToken | An expected per-message token was not | 1056 | | received. | 1057 +------------------+------------------------------------------------+ 1059 A "true" return value for any of the above methods indicates that the 1060 token exhibited the specified property. The application must 1061 determine the appropriate course of action for these supplementary 1062 values. They are not treated as errors by the GSS-API. 1064 4.13. Names 1066 A name is used to identify a person or entity. GSS-API authenticates 1067 the relationship between a name and the entity claiming the name. 1069 Since different authentication mechanisms may employ different 1070 namespaces for identifying their principals, GSS-API's naming support 1071 is necessarily complex in multi-mechanism environments (or even in 1072 some single-mechanism environments where the underlying mechanism 1073 supports multiple namespaces). 1075 Two distinct conceptual representations are defined for names: 1077 1) A GSS-API form represented by implementations of the GSSName 1078 interface: A single GSSName object may contain multiple names from 1079 different namespaces, but all names should refer to the same 1080 entity. An example of such an internal name would be the name 1081 returned from a call to the getName method of the GSSCredential 1082 interface, when applied to a credential containing credential 1083 elements for multiple authentication mechanisms employing 1084 different namespaces. This GSSName object will contain a distinct 1085 name for the entity for each authentication mechanism. 1087 For GSS-API implementations supporting multiple namespaces, 1088 GSSName implementations must contain sufficient information to 1089 determine the namespace to which each primitive name belongs. 1091 2) Mechanism-specific contiguous byte array and string forms: 1092 Different GSSName initialization methods are provided to handle 1093 both byte array and string formats and to accommodate various 1094 calling applications and name types. These formats are capable of 1095 containing only a single name (from a single namespace). 1096 Contiguous string names are always accompanied by an object 1097 identifier specifying the namespace to which the name belongs, and 1098 their format is dependent on the authentication mechanism that 1099 employs that name. The string name forms are assumed to be 1100 printable, and may therefore be used by GSS-API applications for 1101 communication with their users. The byte array name formats are 1102 assumed to be in non-printable formats (e.g., the byte array 1103 returned from the export method of the GSSName interface). 1105 A GSSName object can be converted to a contiguous representation by 1106 using the toString method. This will guarantee that the name will be 1107 converted to a printable format. Different initialization methods in 1108 the GSSName interface are defined allowing support for multiple 1109 syntaxes for each supported namespace, and allowing users the freedom 1110 to choose a preferred name representation. The toString method 1111 should use an implementation-chosen printable syntax for each 1112 supported name type. To obtain the printable name type, 1113 getStringNameType method can be used. 1115 There is no guarantee that calling the toString method on the GSSName 1116 interface will produce the same string form as the original imported 1117 string name. Furthermore, it is possible that the name was not even 1118 constructed from a string representation. The same applies to 1119 namespace identifiers, which may not necessarily survive unchanged 1120 after a journey through the internal name form. An example of this 1121 might be a mechanism that authenticates X.500 names, but provides an 1122 algorithmic mapping of Internet DNS names into X.500. That 1123 mechanism's implementation of GSSName might, when presented with a 1124 DNS name, generate an internal name that contained both the original 1125 DNS name and the equivalent X.500 name. Alternatively, it might only 1126 store the X.500 name. In the latter case, the toString method of 1127 GSSName would most likely generate a printable X.500 name, rather 1128 than the original DNS name. 1130 The context acceptor can obtain a GSSName object representing the 1131 entity performing the context initiation (through the usage of 1132 getSrcName method). Since this name has been authenticated by a 1133 single mechanism, it contains only a single name (even if the 1134 internal name presented by the context initiator to the GSSContext 1135 object had multiple components). Such names are termed internal- 1136 mechanism names (or MNs), and the names emitted by GSSContext 1137 interface in the getSrcName and getTargName are always of this type. 1138 Since some applications may require MNs without wanting to incur the 1139 overhead of an authentication operation, creation methods are 1140 provided that take not only the name buffer and name type, but also 1141 the mechanism oid for which this name should be created. When 1142 dealing with an existing GSSName object, the canonicalize method may 1143 be invoked to convert a general internal name into an MN. 1145 GSSName objects can be compared using their equal method, which 1146 returns "true" if the two names being compared refer to the same 1147 entity. This is the preferred way to perform name comparisons 1148 instead of using the printable names that a given GSS-API 1149 implementation may support. Since GSS-API assumes that all primitive 1150 names contained within a given internal name refer to the same 1151 entity, equal can return "true" if the two names have at least one 1152 primitive name in common. If the implementation embodies knowledge 1153 of equivalence relationships between names taken from different 1154 namespaces, this knowledge may also allow successful comparisons of 1155 internal names containing no overlapping primitive elements. 1157 When used in large access control lists, the overhead of creating a 1158 GSSName object on each name and invoking the equal method on each 1159 name from the Access Control List (ACL) may be prohibitive. As an 1160 alternative way of supporting this case, GSS-API defines a special 1161 form of the contiguous byte array name, which may be compared 1162 directly (byte by byte). Contiguous names suitable for comparison 1163 are generated by the export method. Exported names may be re- 1164 imported by using the byte array constructor and specifying the 1165 NT_EXPORT_NAME as the name type object identifier. The resulting 1166 GSSName name will also be a MN. 1168 The GSSName interface defines public static Oid objects representing 1169 the standard name types. Structurally, an exported name object 1170 consists of a header containing an OID identifying the mechanism that 1171 authenticated the name, and a trailer containing the name itself, 1172 where the syntax of the trailer is defined by the individual 1173 mechanism specification. Detailed description of the format is 1174 specified in the language-independent GSS-API specification 1175 [RFC2743]. 1177 Note that the results obtained by using the equals method will in 1178 general be different from those obtained by invoking canonicalize and 1179 export, and then comparing the byte array output. The first series 1180 of operation determines whether two (unauthenticated) names identify 1181 the same principal; the second whether a particular mechanism would 1182 authenticate them as the same principal. These two operations will 1183 in general give the same results only for MNs. 1185 It is important to note that the above are guidelines as to how 1186 GSSName implementations should behave, and are not intended to be 1187 specific requirements of how name objects must be implemented. The 1188 mechanism designers are free to decide on the details of their 1189 implementations of the GSSName interface as long as the behavior 1190 satisfies the above guidelines. 1192 4.14. Channel Bindings 1194 GSS-API supports the use of user-specified tags to identify a given 1195 context to the peer application. These tags are intended to be used 1196 to identify the particular communications channel that carries the 1197 context. Channel bindings are communicated to the GSS-API using the 1198 ChannelBinding object. The application may use byte arrays to 1199 specify the application data to be used in the channel binding as 1200 well as using instances of the InetAddress. The InetAddress for the 1201 initiator and/or acceptor can be used within an instance of a 1202 ChannelBinding. ChannelBinding can be set for the GSSContext object 1203 using the setChannelBinding method before the first call to init or 1204 accept has been performed. Unless the setChannelBinding method has 1205 been used to set the ChannelBinding for a GSSContext object, "null" 1206 ChannelBinding will be assumed. InetAddress is currently the only 1207 address type defined within the Java platform and as such, it is the 1208 only one supported within the ChannelBinding class. Applications 1209 that use other types of addresses can include them as part of the 1210 application-specific data. 1212 Conceptually, the GSS-API concatenates the initiator and acceptor 1213 address information, and the application-supplied byte array to form 1214 an octet-string. The mechanism calculates a Message Integrity Code 1215 (MIC) over this octet-string and binds the MIC to the context 1216 establishment token emitted by the init method of the GSSContext 1217 interface. The same bindings are set by the context acceptor for its 1218 GSSContext object and during processing of the accept method, a MIC 1219 is calculated in the same way. The calculated MIC is compared with 1220 that found in the token, and if the MICs differ, accept will throw a 1221 GSSException with the major code set to BAD_BINDINGS, and the context 1222 will not be established. Some mechanisms may include the actual 1223 channel binding data in the token (rather than just a MIC); 1224 applications should therefore not use confidential data as channel- 1225 binding components. 1227 Individual mechanisms may impose additional constraints on addresses 1228 that may appear in channel bindings. For example, a mechanism may 1229 verify that the initiator address field of the channel binding 1230 contains the correct network address of the host system. Portable 1231 applications should therefore ensure that they either provide correct 1232 information for the address fields, or omit the setting of the 1233 addressing information. 1235 4.15. Optional Parameters 1237 Whenever the application wishes to omit an optional parameter the 1238 "null" value shall be used. The detailed method descriptions 1239 indicate which parameters are optional. Method overloading has also 1240 been used as a technique to indicate default parameters. 1242 5. Introduction to GSS-API Classes and Interfaces 1244 This section presents a brief description of the classes and 1245 interfaces that constitute the GSS-API. The implementations of these 1246 are obtained from the CLASSPATH defined by the application. If Java 1247 GSS becomes part of the standard Java APIs, then these classes will 1248 be available by default on all systems as part of the JRE's system 1249 classes. 1251 This section also shows the corresponding RFC 2743 [RFC2743] 1252 functionality implemented by each of the classes. Detailed 1253 description of these classes and their methods is presented in 1254 section 6 1256 5.1. GSSManager Class 1258 This abstract class serves as a factory to instantiate 1259 implementations of the GSS-API interfaces and also provides methods 1260 to make queries about underlying security mechanisms. 1262 A default implementation can be obtained using the static method 1263 getInstance(). Applications that desire to provide their own 1264 implementation of the GSSManager class can simply extend the abstract 1265 class themselves. 1267 This class contains equivalents of the following RFC 2743 [RFC2743] 1268 routines: 1270 +----------------------------+-------------------------+------------+ 1271 | RFC 2743 Routine | Function | Section(s) | 1272 +----------------------------+-------------------------+------------+ 1273 | gss_import_name | Create an internal name | 6.1.6 - | 1274 | | from the supplied | 6.1.9 | 1275 | | information. | | 1276 | | | | 1277 | gss_acquire_cred | Acquire credential for | 6.1.10 - | 1278 | | use. | 6.1.12 | 1279 | | | | 1280 | gss_import_sec_context | Create a previously | 6.1.15 | 1281 | | exported context. | | 1282 | | | | 1283 | gss_indicate_mechs | List the mechanisms | 6.1.3 | 1284 | | supported by this GSS- | | 1285 | | API implementation. | | 1286 | | | | 1287 | gss_inquire_mechs_for_name | List the mechanisms | 6.1.5 | 1288 | | supporting the | | 1289 | | specified name type. | | 1290 | | | | 1291 | gss_inquire_names_for_mech | List the name types | 6.1.4 | 1292 | | supported by the | | 1293 | | specified mechanism. | | 1294 +----------------------------+-------------------------+------------+ 1296 5.2. GSSName Interface 1298 GSS-API names are represented in the Java bindings through the 1299 GSSName interface. Different name formats and their definitions are 1300 identified with Universal Object Identifiers (oids). The format of 1301 the names can be derived based on the unique oid of each name type. 1302 The following GSS-API routines are provided by the GSSName interface: 1304 +-----------------------+------------------------------+------------+ 1305 | RFC 2743 Routine | Function | Section(s) | 1306 +-----------------------+------------------------------+------------+ 1307 | gss_display_name | Convert internal name | 6.2.7 | 1308 | | representation to text | | 1309 | | format. | | 1310 | | | | 1311 | gss_compare_name | Compare two internal names. | 6.2.3, | 1312 | | | 6.2.4 | 1313 | | | | 1314 | gss_release_name | Release resources associated | N/A | 1315 | | with the internal name. | | 1316 | | | | 1317 | gss_canonicalize_name | Convert an internal name to | 6.2.5 | 1318 | | a mechanism name. | | 1319 | | | | 1320 | gss_export_name | Convert a mechanism name to | 6.2.6 | 1321 | | export format. | | 1322 | | | | 1323 | gss_duplicate_name | Create a copy of the | N/A | 1324 | | internal name. | | 1325 +-----------------------+------------------------------+------------+ 1327 The gss_release_name call is not provided as Java does its own 1328 garbage collection. The gss_duplicate_name call is also redundant; 1329 the GSSName interface has no mutator methods that can change the 1330 state of the object so it is safe for sharing across threads. 1332 5.3. GSSCredential Interface 1334 The GSSCredential interface is responsible for the encapsulation of 1335 GSS-API credentials. Credentials identify a single entity and 1336 provide the necessary cryptographic information to enable the 1337 creation of a context on behalf of that entity. A single credential 1338 may contain multiple mechanism-specific credentials, each referred to 1339 as a credential element. The GSSCredential interface provides the 1340 functionality of the following GSS-API routines: 1342 +--------------------------+---------------------------+------------+ 1343 | RFC 2743 Routine | Function | Section(s) | 1344 +--------------------------+---------------------------+------------+ 1345 | gss_add_cred | Constructs credentials | 6.3.12 | 1346 | | incrementally. | | 1347 | | | | 1348 | gss_inquire_cred | Obtain information about | 6.3.4 - | 1349 | | credential. | 6.3.11 | 1350 | | | | 1351 | gss_inquire_cred_by_mech | Obtain per-mechanism | 6.3.5 - | 1352 | | information about a | 6.3.10 | 1353 | | credential. | | 1354 | | | | 1355 | gss_release_cred | Dispose of credentials | 6.3.3 | 1356 | | after use. | | 1357 +--------------------------+---------------------------+------------+ 1359 5.4. GSSContext Interface 1361 This interface encapsulates the functionality of context-level calls 1362 required for security context establishment and management between 1363 peers as well as the per-message services offered to applications. A 1364 context is established between a pair of peers and allows the usage 1365 of security services on a per-message basis on application data. It 1366 is created over a single security mechanism. The GSSContext 1367 interface provides the functionality of the following GSS-API 1368 routines: 1370 +------------------------+-----------------------------+------------+ 1371 | RFC 2743 Routine | Function | Section(s) | 1372 +------------------------+-----------------------------+------------+ 1373 | gss_init_sec_context | Initiate the creation of a | 6.4.3, | 1374 | | security context with a | 6.4.4 | 1375 | | peer. | | 1376 | | | | 1377 | gss_accept_sec_context | Accept a security context | 6.4.5, | 1378 | | initiated by a peer. | 6.4.6 | 1379 | | | | 1380 | gss_delete_sec_context | Destroy a security context. | 6.4.8 | 1381 | | | | 1382 | gss_context_time | Obtain remaining context | 6.4.33 | 1383 | | time. | | 1384 | | | | 1385 | gss_inquire_context | Obtain context | 6.4.24 - | 1386 | | characteristics. | 6.4.38 | 1387 | | | | 1388 | gss_wrap_size_limit | Determine token-size limit | 6.4.9 | 1389 | | for gss_wrap. | | 1390 | | | | 1391 | gss_export_sec_context | Transfer security context | 6.4.14 | 1392 | | to another process. | | 1393 | | | | 1394 | gss_get_mic | Calculate a cryptographic | 6.4.12 | 1395 | | Message Integrity Code | | 1396 | | (MIC) for a message. | | 1397 | | | | 1398 | gss_verify_mic | Verify integrity on a | 6.4.13 | 1399 | | received message. | | 1400 | | | | 1401 | gss_wrap | Attach a MIC to a message | 6.4.10 | 1402 | | and optionally encrypt the | | 1403 | | message content. | | 1404 | | | | 1405 | gss_unwrap | Obtain a previously wrapped | 6.4.11 | 1406 | | application message | | 1407 | | verifying its integrity and | | 1408 | | optionally decrypting it. | | 1409 +------------------------+-----------------------------+------------+ 1411 The functionality offered by the gss_process_context_token routine 1412 has not been included in the Java bindings specification. The 1413 corresponding functionality of gss_delete_sec_context has also been 1414 modified to not return any peer tokens. This has been proposed in 1415 accordance to the recommendations stated in RFC 2743 [RFC2743]. 1416 GSSContext does offer the functionality of destroying the locally 1417 stored context information. 1419 5.5. MessageProp Class 1421 This helper class is used in the per-message operations on the 1422 context. An instance of this class is created by the application and 1423 then passed into the per-message calls. In some cases, the 1424 application conveys information to the GSS-API implementation through 1425 this object and in other cases the GSS-API returns information to the 1426 application by setting it in this object. See the description of the 1427 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1428 GSSContext interfaces for details. 1430 5.6. GSSException Class 1432 Exceptions are used in the Java bindings to signal fatal errors to 1433 the calling applications. This replaces the major and minor codes 1434 used in the C-bindings specification as a method of signaling 1435 failures. The GSSException class handles both minor and major codes, 1436 as well as their translation into textual representation. All GSS- 1437 API methods are declared as throwing this exception. 1439 +--------------------+----------------------------+-----------------+ 1440 | RFC 2743 Routine | Function | Section | 1441 +--------------------+----------------------------+-----------------+ 1442 | gss_display_status | Retrieve textual | 6.8.5, 6.8.6, | 1443 | | representation of error | 6.8.9, 6.8.10 | 1444 | | codes. | | 1445 +--------------------+----------------------------+-----------------+ 1447 5.7. Oid Class 1449 This utility class is used to represent Universal Object Identifiers 1450 and their associated operations. GSS-API uses object identifiers to 1451 distinguish between security mechanisms and name types. This class, 1452 aside from being used whenever an object identifier is needed, 1453 implements the following GSS-API functionality: 1455 +-------------------------+-------------------------------+---------+ 1456 | RFC 2743 Routine | Function | Section | 1457 +-------------------------+-------------------------------+---------+ 1458 | gss_test_oid_set_member | Determine if the specified | 6.7.5 | 1459 | | oid is part of a set of oids. | | 1460 +-------------------------+-------------------------------+---------+ 1462 5.8. ChannelBinding Class 1464 An instance of this class is used to specify channel binding 1465 information to the GSSContext object before the start of a security 1466 context establishment. The application may use a byte array to 1467 specify application data to be used in the channel binding as well as 1468 to use instances of the InetAddress. InetAddress is currently the 1469 only address type defined within the Java platform and as such, it is 1470 the only one supported within the ChannelBinding class. Applications 1471 that use other types of addresses can include them as part of the 1472 application data. 1474 6. Detailed GSS-API Class Description 1476 This section lists a detailed description of all the public methods 1477 that each of the GSS-API classes and interfaces must provide. 1479 6.1. public abstract class GSSManager 1481 The GSSManager class is an abstract class that serves as a factory 1482 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1483 also provides methods for applications to determine what mechanisms 1484 are available from the GSS implementation and what name types these 1485 mechanisms support. An instance of the default GSSManager subclass 1486 may be obtained through the static method getInstance(), but 1487 applications are free to instantiate other subclasses of GSSManager. 1489 All but one method in this class are declared abstract. This means 1490 that subclasses have to provide the complete implementation for those 1491 methods. The only exception to this is the static method 1492 getInstance(), which will have platform-specific code to return an 1493 instance of the default subclass. 1495 Platform providers of GSS are required not to add any constructors to 1496 this class, private, public, or protected. This will ensure that all 1497 subclasses invoke only the default constructor provided to the base 1498 class by the compiler. 1500 A subclass extending the GSSManager abstract class may be implemented 1501 as a modular provider-based layer that utilizes some well-known 1502 service provider specification. The GSSManager API provides the 1503 application with methods to set provider preferences on such an 1504 implementation. These methods also allow the implementation to throw 1505 a well-defined exception in case provider-based configuration is not 1506 supported. Applications that expect to be portable should be aware 1507 of this and recover cleanly by catching the exception. 1509 It is envisioned that there will be three most common ways in which 1510 providers will be used: 1512 1) The application does not care about what provider is used (the 1513 default case). 1515 2) The application wants a particular provider to be used 1516 preferentially, either for a particular mechanism or all the time, 1517 irrespective of the mechanism. 1519 3) The application wants to use the locally configured providers as 1520 far as possible, but if support is missing for one or more 1521 mechanisms, then it wants to fall back on its own provider. 1523 The GSSManager class has two methods that enable these modes of 1524 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1525 have the effect of creating an ordered list of pairs 1526 where each pair indicates a preference of provider for a given oid. 1528 The use of these methods does not require any knowledge of whatever 1529 service provider specification the GSSManager subclass follows. It 1530 is hoped that these methods will serve the needs of most 1531 applications. Additional methods may be added to an extended 1532 GSSManager that could be part of a service provider specification 1533 that is standardized later. 1535 6.1.1. Example Code 1537 1538 GSSManager mgr = GSSManager.getInstance(); 1540 // What mechs are available to us? 1542 Oid[] supportedMechs = mgr.getMechs(); 1544 // Set a preference for the provider to be used when support 1545 // is needed for the mechanisms: 1546 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1548 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1549 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1551 Provider p = (Provider) (new com.foo.security.Provider()); 1553 mgr.addProviderAtFront(p, krb); 1554 mgr.addProviderAtFront(p, spkm1); 1556 // What name types does this spkm implementation support? 1557 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1558 1560 6.1.2. getInstance 1562 public static GSSManager getInstance() 1564 Returns the default GSSManager implementation. 1566 6.1.3. getMechs 1568 public abstract Oid[] getMechs() 1570 Returns an array of Oid objects indicating the mechanisms available 1571 to GSS-API callers. A "null" value is returned when no mechanism are 1572 available (an example of this would be when mechanism are dynamically 1573 configured, and currently no mechanisms are installed). 1575 6.1.4. getNamesForMech 1577 public abstract Oid[] getNamesForMech(Oid mech) 1578 throws GSSException 1580 Returns name type Oid's supported by the specified mechanism. 1582 Parameters: 1584 mech The Oid object for the mechanism to query. 1586 6.1.5. getMechsForName 1588 public abstract Oid[] getMechsForName(Oid nameType) 1590 Returns an array of Oid objects corresponding to the mechanisms that 1591 support the specific name type. "null" is returned when no mechanisms 1592 are found to support the specified name type. 1594 Parameters: 1596 nameType The Oid object for the name type. 1598 6.1.6. createName 1600 public abstract GSSName createName(String nameStr, Oid nameType) 1601 throws GSSException 1603 Factory method to convert a contiguous string name from the specified 1604 namespace to a GSSName object. In general, the GSSName object 1605 created will not be an MN; two examples that are exceptions to this 1606 are when the namespace type parameter indicates NT_EXPORT_NAME or 1607 when the GSS-API implementation is not multi-mechanism. 1609 Parameters: 1611 nameStr The string representing a printable form of the 1612 name to create. 1614 nameType The Oid specifying the namespace of the printable 1615 name is supplied. Note that nameType serves to 1616 describe and qualify the interpretation of the 1617 input nameStr, it does not necessarily imply a 1618 type for the output GSSName implementation. The 1619 "null" value can be used to specify that a 1620 mechanism-specific default printable syntax 1621 should be assumed by each mechanism that examines 1622 nameStr. 1624 6.1.7. createName 1626 public abstract GSSName createName(byte[] name, Oid nameType) 1627 throws GSSException 1629 Factory method to convert a contiguous byte array containing a name 1630 from the specified namespace to a GSSName object. In general, the 1631 GSSName object created will not be an MN; two examples that are 1632 exceptions to this are when the namespace type parameter indicates 1633 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1634 mechanism. 1636 Parameters: 1638 name The byte array containing the name to create. 1640 nameType The Oid specifying the namespace of the name 1641 supplied in the byte array. Note that nameType 1642 serves to describe and qualify the interpretation 1643 of the input name byte array; it does not 1644 necessarily imply a type for the output GSSName 1645 implementation. The "null" value can be used to 1646 specify that a mechanism-specific default syntax 1647 should be assumed by each mechanism that examines 1648 the byte array. 1650 6.1.8. createName 1652 public abstract GSSName createName(String nameStr, Oid nameType, 1653 Oid mech) throws GSSException 1655 Factory method to convert a contiguous string name from the specified 1656 namespace to a GSSName object that is a mechanism name (MN). In 1657 other words, this method is a utility that does the equivalent of two 1658 steps: the createName described in section 6.1.6, and then also the 1659 GSSName.canonicalize() described in section 6.2.5. 1661 Parameters: 1663 nameStr The string representing a printable form of the 1664 name to create. 1666 nameType The Oid specifying the namespace of the printable 1667 name supplied. Note that nameType serves to 1668 describe and qualify the interpretation of the 1669 input nameStr; it does not necessarily imply a 1670 type for the output GSSName implementation. The 1671 "null" value can be used to specify that a 1672 mechanism-specific default printable syntax 1673 should be assumed when the mechanism examines 1674 nameStr. 1676 mech Oid specifying the mechanism for which this name 1677 should be created. 1679 6.1.9. createName 1681 public abstract GSSName createName(byte[] name, Oid nameType, 1682 Oid mech) throws GSSException 1684 Factory method to convert a contiguous byte array containing a name 1685 from the specified namespace to a GSSName object that is an MN. In 1686 other words, this method is a utility that does the equivalent of two 1687 steps: the createName described in section 6.1.7, and then also the 1688 GSSName.canonicalize() described in section 6.2.5. 1690 Parameters: 1692 name The byte array representing the name to create. 1694 nameType The Oid specifying the namespace of the name 1695 supplied in the byte array. Note that nameType 1696 serves to describe and qualify the interpretation 1697 of the input name byte array, it does not 1698 necessarily imply a type for the output GSSName 1699 implementation. The "null" value can be used to 1700 specify that a mechanism-specific default syntax 1701 should be assumed by each mechanism that examines 1702 the byte array. 1704 mech Oid specifying the mechanism for which this name 1705 should be created. 1707 6.1.10. createCredential 1709 public abstract GSSCredential createCredential(int usage) 1710 throws GSSException 1712 Factory method for acquiring default credentials. This will cause 1713 the GSS-API to use system-specific defaults for the set of 1714 mechanisms, name, and a DEFAULT lifetime. 1716 Parameters: 1718 usage The intended usage for this credential object. 1719 The value of this parameter must be one of: 1721 GSSCredential.INITIATE_AND_ACCEPT(0), 1722 GSSCredential.INITIATE_ONLY(1), or 1723 GSSCredential.ACCEPT_ONLY(2) 1725 6.1.11. createCredential 1727 public abstract GSSCredential createCredential(GSSName aName, 1728 int lifetime, Oid mech, int usage) 1729 throws GSSException 1731 Factory method for acquiring a single mechanism credential. 1733 Parameters: 1735 aName Name of the principal for whom this credential is 1736 to be acquired. Use "null" to specify the 1737 default principal. 1739 lifetime The number of seconds that credentials should 1740 remain valid. Use 1741 GSSCredential.INDEFINITE_LIFETIME to request that 1742 the credentials have the maximum permitted 1743 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1744 request default credential lifetime. 1746 mech The oid of the desired mechanism. Use "(Oid) 1747 null" to request the default mechanism(s). 1749 usage The intended usage for this credential object. 1750 The value of this parameter must be one of: 1752 GSSCredential.INITIATE_AND_ACCEPT(0), 1753 GSSCredential.INITIATE_ONLY(1), or 1754 GSSCredential.ACCEPT_ONLY(2) 1756 6.1.12. createCredential 1758 public abstract GSSCredential createCredential(GSSName aName, 1759 int lifetime, Oid[] mechs, int usage) 1760 throws GSSException 1762 Factory method for acquiring credentials over a set of mechanisms. 1763 Acquires credentials for each of the mechanisms specified in the 1764 array called mechs. To determine the list of mechanisms' for which 1765 the acquisition of credentials succeeded, the caller should use the 1766 GSSCredential.getMechs() method. 1768 Parameters: 1770 aName Name of the principal for whom this credential is 1771 to be acquired. Use "null" to specify the 1772 default principal. 1774 lifetime The number of seconds that credentials should 1775 remain valid. Use 1776 GSSCredential.INDEFINITE_LIFETIME to request that 1777 the credentials have the maximum permitted 1778 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1779 request default credential lifetime. 1781 mechs The array of mechanisms over which the credential 1782 is to be acquired. Use "(Oid[]) null" for 1783 requesting a system-specific default set of 1784 mechanisms. 1786 usage The intended usage for this credential object. 1787 The value of this parameter must be one of: 1789 GSSCredential.INITIATE_AND_ACCEPT(0), 1790 GSSCredential.INITIATE_ONLY(1), or 1791 GSSCredential.ACCEPT_ONLY(2) 1793 6.1.13. createContext 1795 public abstract GSSContext createContext(GSSName peer, Oid mech, 1796 GSSCredential myCred, int lifetime) 1797 throws GSSException 1799 Factory method for creating a context on the initiator's side. 1800 Context flags may be modified through the mutator methods prior to 1801 calling GSSContext.initSecContext(). 1803 Parameters: 1805 peer Name of the target peer. 1807 mech Oid of the desired mechanism. Use "(Oid) null" 1808 to request the default mechanism. 1810 myCred Credentials of the initiator. Use "null" to act 1811 as a default initiator principal. 1813 lifetime The request lifetime, in seconds, for the 1814 context. Use GSSContext.INDEFINITE_LIFETIME and 1815 GSSContext.DEFAULT_LIFETIME to request indefinite 1816 or default context lifetime. 1818 6.1.14. createContext 1820 public abstract GSSContext createContext(GSSCredential myCred) 1821 throws GSSException 1823 Factory method for creating a context on the acceptor' side. The 1824 context's properties will be determined from the input token supplied 1825 to the accept method. 1827 Parameters: 1829 myCred Credentials for the acceptor. Use "null" to act 1830 as a default acceptor principal. 1832 6.1.15. createContext 1834 public abstract GSSContext createContext(byte[] interProcessToken) 1835 throws GSSException 1837 Factory method for creating a previously exported context. The 1838 context properties will be determined from the input token and can't 1839 be modified through the set methods. 1841 Parameters: 1843 interProcessToken The token previously emitted from the export 1844 method. 1846 6.1.16. addProviderAtFront 1848 public abstract void addProviderAtFront(Provider p, Oid mech) 1849 throws GSSException 1851 This method is used to indicate to the GSSManager that the 1852 application would like a particular provider to be used ahead of all 1853 others when support is desired for the given mechanism. When a value 1854 of "null" is used instead of an Oid for the mechanism, the GSSManager 1855 must use the indicated provider ahead of all others no matter what 1856 the mechanism is. Only when the indicated provider does not support 1857 the needed mechanism should the GSSManager move on to a different 1858 provider. 1860 Calling this method repeatedly preserves the older settings but 1861 lowers them in preference thus forming an ordered list of provider 1862 and Oid pairs that grows at the top. 1864 Calling addProviderAtFront with a null Oid will remove all previous 1865 preferences that were set for this provider in the GSSManager 1866 instance. Calling addProviderAtFront with a non-null Oid will remove 1867 any previous preference that was set using this mechanism and this 1868 provider together. 1870 If the GSSManager implementation does not support an SPI with a 1871 pluggable provider architecture, it should throw a GSSException with 1872 the status code GSSException.UNAVAILABLE to indicate that the 1873 operation is unavailable. 1875 Parameters: 1877 p The provider instance that should be used 1878 whenever support is needed for mech. 1880 mech The mechanism for which the provider is being 1881 set. 1883 6.1.17. Example Code 1885 Suppose an application desired that the provider A always be checked 1886 first when any mechanism is needed, it would call: 1888 1889 GSSManager mgr = GSSManager.getInstance(); 1890 // mgr may at this point have its own pre-configured list 1891 // of provider preferences. The following will prepend to 1892 // any such list: 1894 mgr.addProviderAtFront(A, null); 1895 1897 Now if it also desired that the mechanism of Oid m1 always be 1898 obtained from the provider B before the previously set A was checked, 1899 it would call: 1901 1902 mgr.addProviderAtFront(B, m1); 1903 1905 The GSSManager would then first check with B if m1 was needed. In 1906 case B did not provide support for m1, the GSSManager would continue 1907 on to check with A. If any mechanism m2 is needed where m2 is 1908 different from m1, then the GSSManager would skip B and check with A 1909 directly. 1911 Suppose, at a later time, the following call is made to the same 1912 GSSManager instance: 1914 1915 mgr.addProviderAtFront(B, null) 1916 1918 then the previous setting with the pair (B, m1) is subsumed by this 1919 and should be removed. Effectively, the list of preferences now 1920 becomes {(B, null), (A, null), ... //followed by the pre-configured 1921 list. 1923 Please note, however, that the following call: 1925 1926 mgr.addProviderAtFront(A, m3) 1927 1929 does not subsume the previous setting of (A, null), and the list will 1930 effectively become {(A, m3), (B, null), (A, null), ...} 1932 6.1.18. addProviderAtEnd 1934 public abstract void addProviderAtEnd(Provider p, Oid mech) 1935 throws GSSException 1937 This method is used to indicate to the GSSManager that the 1938 application would like a particular provider to be used if no other 1939 provider can be found that supports the given mechanism. When a 1940 value of "null" is used instead of an Oid for the mechanism, the 1941 GSSManager must use the indicated provider for any mechanism. 1943 Calling this method repeatedly preserves the older settings, but 1944 raises them above newer ones in preference thus forming an ordered 1945 list of providers and Oid pairs that grows at the bottom. Thus, the 1946 older provider settings will be utilized first before this one is. 1948 If there are any previously existing preferences that conflict with 1949 the preference being set here, then the GSSManager should ignore this 1950 request. 1952 If the GSSManager implementation does not support an SPI with a 1953 pluggable provider architecture, it should throw a GSSException with 1954 the status code GSSException.UNAVAILABLE to indicate that the 1955 operation is unavailable. 1957 Parameters: 1959 p The provider instance that should be used 1960 whenever support is needed for mech. 1962 mech The mechanism for which the provider is being 1963 set. 1965 6.1.19. Example Code 1967 Suppose an application desired that when a mechanism of Oid m1 is 1968 needed, the system default providers always be checked first, and 1969 only when they do not support m1 should a provider A be checked. It 1970 would then make the call: 1972 1973 GSSManager mgr = GSSManager.getInstance(); 1975 mgr.addProviderAtEnd(A, m1); 1976 1977 Now, if it also desired that for all mechanisms the provider B be 1978 checked after all configured providers have been checked, it would 1979 then call: 1981 1982 mgr.addProviderAtEnd(B, null); 1983 1985 Effectively, the list of preferences now becomes {..., (A, m1), (B, 1986 null)}. 1988 Suppose, at a later time, the following call is made to the same 1989 GSSManager instance: 1991 1992 mgr.addProviderAtEnd(B, m2) 1993 1995 then the previous setting with the pair (B, null) subsumes this; 1996 therefore, this request should be ignored. The same would happen if 1997 a request is made for the already existing pairs of (A, m1) or (B, 1998 null). 2000 Please note, however, that the following call: 2002 2003 mgr.addProviderAtEnd(A, null) 2004 2006 is not subsumed by the previous setting of (A, m1) and the list will 2007 effectively become {..., (A, m1), (B, null), (A, null)}. 2009 6.2. public interface GSSName 2011 This interface encapsulates a single GSS-API principal entity. 2012 Different name formats and their definitions are identified with 2013 Universal Object Identifiers (Oids). The format of the names can be 2014 derived based on the unique oid of its namespace type. 2016 6.2.1. Example Code 2018 Included below are code examples utilizing the GSSName interface. 2019 The code below creates a GSSName, converts it to a mechanism name 2020 (MN), performs a comparison, obtains a printable representation of 2021 the name, exports it and then re-imports to obtain a new GSSName. 2023 2024 GSSManager mgr = GSSManager.getInstance(); 2026 // create a host-based service name 2027 GSSName name = mgr.createName("service@host", 2028 GSSName.NT_HOSTBASED_SERVICE); 2030 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 2032 GSSName mechName = name.canonicalize(krb5); 2034 // the above two steps are equivalent to the following 2035 GSSName mechName = mgr.createName("service@host", 2036 GSSName.NT_HOSTBASED_SERVICE, krb5); 2038 // perform name comparison 2039 if (name.equals(mechName)) 2040 print("Names are equals."); 2042 // obtain textual representation of name and its printable 2043 // name type 2044 print(mechName.toString() + 2045 mechName.getStringNameType().toString()); 2047 // export and re-import the name 2048 byte[] exportName = mechName.export(); 2050 // create a new name object from the exported buffer 2051 GSSName newName = mgr.createName(exportName, 2052 GSSName.NT_EXPORT_NAME); 2053 2055 6.2.2. Static Constants 2057 public static final Oid NT_HOSTBASED_SERVICE 2059 Oid indicating a host-based service name form. It is used to 2060 represent services associated with host computers. This name form is 2061 constructed using two elements, "service" and "hostname", as follows: 2063 service@hostname 2065 Values for the "service" element are registered with the IANA. It 2066 represents the following value: { iso(1) member-body(2) Unites 2067 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2068 service_name(4) } 2070 public static final Oid NT_USER_NAME 2071 Name type to indicate a named user on a local system. It represents 2072 the following value: { iso(1) member-body(2) United States(840) 2073 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2075 public static final Oid NT_MACHINE_UID_NAME 2077 Name type to indicate a numeric user identifier corresponding to a 2078 user on a local system (e.g., Uid). It represents the following 2079 value: { iso(1) member-body(2) United States(840) mit(113554) 2080 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2082 public static final Oid NT_STRING_UID_NAME 2084 Name type to indicate a string of digits representing the numeric 2085 user identifier of a user on a local system. It represents the 2086 following value: { iso(1) member-body(2) United States(840) 2087 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2089 public static final Oid NT_ANONYMOUS 2091 Name type for representing an anonymous entity. It represents the 2092 following value: { iso(1), org(3), dod(6), internet(1), security(5), 2093 nametypes(6), gss-anonymous-name(3) } 2095 public static final Oid NT_EXPORT_NAME 2097 Name type used to indicate an exported name produced by the export 2098 method. It represents the following value: { iso(1), org(3), dod(6), 2099 internet(1), security(5), nametypes(6), gss-api-exported-name(4) } 2101 6.2.3. equals 2103 public boolean equals(GSSName another) throws GSSException 2105 Compares two GSSName objects to determine whether they refer to the 2106 same entity. This method may throw a GSSException when the names 2107 cannot be compared. If either of the names represents an anonymous 2108 entity, the method will return "false". 2110 Parameters: 2112 another GSSName object with which to compare. 2114 6.2.4. equals 2116 public boolean equals(Object another) 2117 A variation of the equals method, described in section 6.2.3, that is 2118 provided to override the Object.equals() method that the implementing 2119 class will inherit. The behavior is exactly the same as that in 2120 section 6.2.3 except that no GSSException is thrown; instead, "false" 2121 will be returned in the situation where an error occurs. (Note that 2122 the Java language specification requires that two objects that are 2123 equal according to the equals(Object) method must return the same 2124 integer result when the hashCode() method is called on them.) 2126 Parameters: 2128 another GSSName object with which to compare. 2130 6.2.5. canonicalize 2132 public GSSName canonicalize(Oid mech) throws GSSException 2134 Creates a mechanism name (MN) from an arbitrary internal name. This 2135 is equivalent to using the factory methods described in sections 2136 6.1.8 or 6.1.9 that take the mechanism name as one of their 2137 parameters. 2139 Parameters: 2141 mech The oid for the mechanism for which the canonical 2142 form of the name is requested. 2144 6.2.6. export 2146 public byte[] export() throws GSSException 2148 Returns a canonical contiguous byte representation of a mechanism 2149 name (MN), suitable for direct, byte-by-byte comparison by 2150 authorization functions. If the name is not an MN, implementations 2151 may throw a GSSException with the NAME_NOT_MN status code. If an 2152 implementation chooses not to throw an exception, it should use some 2153 system-specific default mechanism to canonicalize the name and then 2154 export it. The format of the header of the output buffer is 2155 specified in RFC 2743 [RFC2743]. 2157 6.2.7. toString 2159 public String toString() 2161 Returns a textual representation of the GSSName object. To retrieve 2162 the printed name format, which determines the syntax of the returned 2163 string, the getStringNameType method can be used. 2165 6.2.8. getStringNameType 2167 public Oid getStringNameType() throws GSSException 2169 Returns the oid representing the type of name returned through the 2170 toString method. Using this oid, the syntax of the printable name 2171 can be determined. 2173 6.2.9. isAnonymous 2175 public boolean isAnonymous() 2177 Tests if this name object represents an anonymous entity. Returns 2178 "true" if this is an anonymous name. 2180 6.2.10. isMN 2182 public boolean isMN() 2184 Tests if this name object contains only one mechanism element and is 2185 thus a mechanism name as defined by RFC 2743 [RFC2743]. 2187 6.3. public interface GSSCredential implements Cloneable 2189 This interface encapsulates the GSS-API credentials for an entity. A 2190 credential contains all the necessary cryptographic information to 2191 enable the creation of a context on behalf of the entity that it 2192 represents. It may contain multiple, distinct, mechanism-specific 2193 credential elements, each containing information for a specific 2194 security mechanism, but all referring to the same entity. 2196 A credential may be used to perform context initiation, acceptance, 2197 or both. 2199 GSS-API implementations must impose a local access-control policy on 2200 callers to prevent unauthorized callers from acquiring credentials to 2201 which they are not entitled. GSS-API credential creation is not 2202 intended to provide a "login to the network" function, as such a 2203 function would involve the creation of new credentials rather than 2204 merely acquiring a handle to existing credentials. Such functions, 2205 if required, should be defined in implementation-specific extensions 2206 to the API. 2208 If credential acquisition is time-consuming for a mechanism, the 2209 mechanism may choose to delay the actual acquisition until the 2210 credential is required (e.g., by GSSContext). Such mechanism- 2211 specific implementation decisions should be invisible to the calling 2212 application; thus, the query methods immediately following the 2213 creation of a credential object must return valid credential data, 2214 and may therefore incur the overhead of a deferred credential 2215 acquisition. 2217 Applications will create a credential object passing the desired 2218 parameters. The application can then use the query methods to obtain 2219 specific information about the instantiated credential object 2220 (equivalent to the gss_inquire routines). When the credential is no 2221 longer needed, the application should call the dispose (equivalent to 2222 gss_release_cred) method to release any resources held by the 2223 credential object and to destroy any cryptographically sensitive 2224 information. 2226 Classes implementing this interface also implement the Cloneable 2227 interface. This indicates that the class will support the clone() 2228 method that will allow the creation of duplicate credentials. This 2229 is useful when called just before the add() call to retain a copy of 2230 the original credential. 2232 6.3.1. Example Code 2234 This example code demonstrates the creation of a GSSCredential 2235 implementation for a specific entity, querying of its fields, and its 2236 release when it is no longer needed. 2238 2239 GSSManager mgr = GSSManager.getInstance(); 2241 // start by creating a name object for the entity 2242 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2244 // now acquire credentials for the entity 2245 GSSCredential cred = mgr.createCredential(name, 2246 GSSCredential.ACCEPT_ONLY); 2248 // display credential information - name, remaining lifetime, 2249 // and the mechanisms it has been acquired over 2250 print(cred.getName().toString()); 2251 print(cred.getRemainingLifetime()); 2253 Oid[] mechs = cred.getMechs(); 2254 if (mechs != null) { 2255 for (int i = 0; i < mechs.length; i++) 2256 print(mechs[i].toString()); 2257 } 2258 // release system resources held by the credential 2259 cred.dispose(); 2260 2262 6.3.2. Static Constants 2264 public static final int INITIATE_AND_ACCEPT 2266 Credential usage flag requesting that it be able to be used for both 2267 context initiation and acceptance. The value of this constant is 0. 2269 public static final int INITIATE_ONLY 2271 Credential usage flag requesting that it be able to be used for 2272 context initiation only. The value of this constant is 1. 2274 public static final int ACCEPT_ONLY 2276 Credential usage flag requesting that it be able to be used for 2277 context acceptance only. The value of this constant is 2. 2279 public static final int DEFAULT_LIFETIME 2281 A lifetime constant representing the default credential lifetime. 2282 The value of this constant is 0. 2284 public static final int INDEFINITE_LIFETIME 2286 A lifetime constant representing indefinite credential lifetime. The 2287 value of this constant is the maximum integer value in Java - 2288 Integer.MAX_VALUE. 2290 6.3.3. dispose 2292 public void dispose() throws GSSException 2294 Releases any sensitive information that the GSSCredential object may 2295 be containing. Applications should call this method as soon as the 2296 credential is no longer needed to minimize the time any sensitive 2297 information is maintained. 2299 6.3.4. getName 2301 public GSSName getName() throws GSSException 2303 Retrieves the name of the entity that the credential asserts. 2305 6.3.5. getName 2307 public GSSName getName(Oid mechOID) throws GSSException 2308 Retrieves a mechanism name of the entity that the credential asserts. 2309 Equivalent to calling canonicalize() on the name returned by section 2310 6.3.4. 2312 Parameters: 2314 mechOID The mechanism for which information should be 2315 returned. 2317 6.3.6. getRemainingLifetime 2319 public int getRemainingLifetime() throws GSSException 2321 Returns the remaining lifetime in seconds for a credential. The 2322 remaining lifetime is the minimum lifetime for any of the underlying 2323 credential mechanisms. A return value of 2324 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2325 not expire. A return value of 0 indicates that the credential is 2326 already expired. 2328 6.3.7. getRemainingInitLifetime 2330 public int getRemainingInitLifetime(Oid mech) throws GSSException 2332 Returns the remaining lifetime in seconds for the credential to 2333 remain capable of initiating security contexts under the specified 2334 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2335 indicates that the credential does not expire for context initiation. 2336 A return value of 0 indicates that the credential is already expired. 2338 Parameters: 2340 mechOID The mechanism for which information should be 2341 returned. 2343 6.3.8. getRemainingAcceptLifetime 2345 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2347 Returns the remaining lifetime in seconds for the credential to 2348 remain capable of accepting security contexts under the specified 2349 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2350 indicates that the credential does not expire for context acceptance. 2351 A return value of 0 indicates that the credential is already expired. 2353 Parameters: 2355 mechOID The mechanism for which information should be 2356 returned. 2358 6.3.9. getUsage 2360 public int getUsage() throws GSSException 2362 Returns the credential usage flag as a union over all mechanisms. 2363 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2364 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2366 6.3.10. getUsage 2368 public int getUsage(Oid mechOID) throws GSSException 2370 Returns the credential usage flag for the specified mechanism only. 2371 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2372 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2374 Parameters: 2376 mechOID The mechanism for which information should be 2377 returned. 2379 6.3.11. getMechs 2381 public Oid[] getMechs() throws GSSException 2383 Returns an array of mechanisms supported by this credential. 2385 6.3.12. add 2387 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2388 Oid mech, int usage) throws GSSException 2390 Adds a mechanism-specific credential-element to an existing 2391 credential. This method allows the construction of credentials one 2392 mechanism at a time. 2394 This routine is envisioned to be used mainly by context acceptors 2395 during the creation of acceptance credentials, which are to be used 2396 with a variety of clients using different security mechanisms. 2398 This routine adds the new credential element "in-place". To add the 2399 element in a new credential, first call clone() to obtain a copy of 2400 this credential, then call its add() method. 2402 Parameters: 2404 aName Name of the principal for whom this credential is 2405 to be acquired. Use "null" to specify the 2406 default principal. 2408 initLifetime The number of seconds that credentials should 2409 remain valid for initiating of security contexts. 2410 Use GSSCredential.INDEFINITE_LIFETIME to request 2411 that the credentials have the maximum permitted 2412 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 2413 request default credential lifetime. 2415 acceptLifetime The number of seconds that credentials should 2416 remain valid for accepting of security contexts. 2418 Use GSSCredential.INDEFINITE_LIFETIME to request 2419 that the credentials 2420 have the maximum permitted lifetime. Use 2421 GSSCredential.DEFAULT_LIFETIME to request default 2422 credential lifetime. 2424 mech The mechanisms over which the credential is to be 2425 acquired. 2427 usage The intended usage for this credential object. 2428 The value of this parameter must be one of: 2430 GSSCredential.INITIATE_AND_ACCEPT(0), 2431 GSSCredential.INITIATE_ONLY(1), or 2432 GSSCredential.ACCEPT_ONLY(2) 2434 6.3.13. equals 2436 public boolean equals(Object another) 2438 Tests if this GSSCredential refers to the same entity as the supplied 2439 object. The two credentials must be acquired over the same 2440 mechanisms and must refer to the same principal. Returns "true" if 2441 the two GSSCredentials refer to the same entity; "false" otherwise. 2442 (Note that the Java language specification [JLS] requires that two 2443 objects that are equal according to the equals(Object) method must 2444 return the same integer result when the hashCode() method is called 2445 on them.) 2447 Parameters: 2449 another Another GSSCredential object for comparison. 2451 6.4. public interface GSSContext 2453 This interface encapsulates the GSS-API security context and provides 2454 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2455 available over the context. Security contexts are established 2456 between peers using locally acquired credentials. Multiple contexts 2457 may exist simultaneously between a pair of peers, using the same or 2458 different set of credentials. GSS-API functions in a manner 2459 independent of the underlying transport protocol and depends on its 2460 calling application to transport its tokens between peers. 2462 Before the context establishment phase is initiated, the context 2463 initiator may request specific characteristics desired of the 2464 established context. These can be set using the set methods. After 2465 the context is established, the caller can check the actual 2466 characteristic and services offered by the context using the query 2467 methods. 2469 The context establishment phase begins with the first call to the 2470 init method by the context initiator. During this phase, the 2471 initSecContext and acceptSecContext methods will produce GSS-API 2472 authentication tokens, which the calling application needs to send to 2473 its peer. If an error occurs at any point, an exception will get 2474 thrown and the code will start executing in a catch block where the 2475 exception may contain an output token that should be sent to the peer 2476 for debugging or informational purpose. If not, the normal flow of 2477 code continues and the application can make a call to the 2478 isEstablished() method. If this method returns "false" it indicates 2479 that a token is needed from its peer in order to continue the context 2480 establishment phase. A return value of "true" signals that the local 2481 end of the context is established. This may still require that a 2482 token be sent to the peer, if one is produced by GSS-API. During the 2483 context establishment phase, the isProtReady() method may be called 2484 to determine if the context can be used for the per-message 2485 operations. This allows applications to use per-message operations 2486 on contexts that aren't fully established. 2488 After the context has been established or the isProtReady() method 2489 returns "true", the query routines can be invoked to determine the 2490 actual characteristics and services of the established context. The 2491 application can also start using the per-message methods of wrap and 2492 getMIC to obtain cryptographic operations on application supplied 2493 data. 2495 When the context is no longer needed, the application should call 2496 dispose to release any system resources the context may be using. 2498 6.4.1. Example Code 2500 The example code presented below demonstrates the usage of the 2501 GSSContext interface for the initiating peer. Different operations 2502 on the GSSContext object are presented, including: object 2503 instantiation, setting of desired flags, context establishment, query 2504 of actual context flags, per-message operations on application data, 2505 and finally context deletion. 2507 2508 GSSManager mgr = GSSManager.getInstance(); 2510 // start by creating the name for a service entity 2511 GSSName targetName = mgr.createName("service@host", 2512 GSSName.NT_HOSTBASED_SERVICE); 2513 // create a context using default credentials for the above entity 2514 // and the implementation-specific default mechanism 2515 GSSContext context = mgr.createContext(targetName, 2516 null, /* default mechanism */ 2517 null, /* default credentials */ 2518 GSSContext.INDEFINITE_LIFETIME); 2520 // set desired context options - all others are "false" by default 2521 context.requestConf(true); 2522 context.requestMutualAuth(true); 2523 context.requestReplayDet(true); 2524 context.requestSequenceDet(true); 2526 // establish a context between peers - using byte arrays 2527 byte[]inTok = new byte[0]; 2529 try { 2530 do { 2531 byte[] outTok = context.initSecContext(inTok, 0, 2532 inTok.length); 2534 // send the token if present 2535 if (outTok != null) 2536 sendToken(outTok); 2538 // check if we should expect more tokens 2539 if (context.isEstablished()) 2540 break; 2542 // another token expected from peer 2543 inTok = readToken(); 2545 } while (true); 2547 } catch (GSSException e) { 2548 print("GSSAPI error: " + e.getMessage()); 2550 // If the exception contains an output token, 2551 // it should be sent to the acceptor. 2552 byte[] outTok = e.getOutputToken(); 2553 if (outTok != null) { 2554 sendToken(outTok); 2555 } 2557 return; 2558 } 2560 // display context information 2561 print("Remaining lifetime in seconds = " + context.getLifetime()); 2562 print("Context mechanism = " + context.getMech().toString()); 2563 print("Initiator = " + context.getSrcName().toString()); 2564 print("Acceptor = " + context.getTargName().toString()); 2566 if (context.getConfState()) 2567 print("Confidentiality security service available"); 2569 if (context.getIntegState()) 2570 print("Integrity security service available"); 2572 // perform wrap on an application-supplied message, appMsg, 2573 // using QOP = 0, and requesting privacy service 2574 byte[] appMsg ... 2576 MessageProp mProp = new MessageProp(0, true); 2578 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2580 if (mProp.getPrivacy()) 2581 print("Message protected with privacy."); 2583 sendToken(tok); 2585 // release the local end of the context 2586 context.dispose(); 2587 2589 6.4.2. Static Constants 2591 public static final int DEFAULT_LIFETIME 2593 A lifetime constant representing the default context lifetime. The 2594 value of this constant is 0. 2596 public static final int INDEFINITE_LIFETIME 2598 A lifetime constant representing indefinite context lifetime. The 2599 value of this constant is the maximum integer value in Java - 2600 Integer.MAX_VALUE. 2602 6.4.3. initSecContext 2604 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2605 throws GSSException 2607 Called by the context initiator to start the context creation 2608 process. This method may return an output token that the application 2609 will need to send to the peer for processing by the accept call. The 2610 application can call isEstablished() to determine if the context 2611 establishment phase is complete for this peer. A return value of 2612 "false" from isEstablished() indicates that more tokens are expected 2613 to be supplied to the initSecContext() method. Note that it is 2614 possible that the initSecContext() method will return a token for the 2615 peer and isEstablished() will return "true" also. This indicates 2616 that the token needs to be sent to the peer, but the local end of the 2617 context is now fully established. 2619 Upon completion of the context establishment, the available context 2620 options may be queried through the get methods. 2622 A GSSException will be thrown if the call fails. Users should call 2623 its getOutputToken() method to find out if there is a token that can 2624 be sent to the acceptor to communicate the reason for the error. 2626 Parameters: 2628 inputBuf Token generated by the peer. This parameter is 2629 ignored on the first call. 2631 offset The offset within the inputBuf where the token 2632 begins. 2634 len The length of the token within the inputBuf 2635 (starting at the offset). 2637 6.4.4. Example Code 2638 2639 // Create a new GSSContext implementation object. 2640 // GSSContext wrapper implements interface GSSContext. 2641 GSSContext context = mgr.createContext(...); 2643 byte[] inTok = new byte[0]; 2645 try { 2646 do { 2647 byte[] outTok = context.initSecContext(inTok, 0, 2648 inTok.length); 2650 // send the token if present 2651 if (outTok != null) 2652 sendToken(outTok); 2654 // check if we should expect more tokens 2655 if (context.isEstablished()) 2656 break; 2658 // another token expected from peer 2659 inTok = readToken(); 2660 } while (true); 2662 } catch (GSSException e) { 2663 print("GSSAPI error: " + e.getMessage()); 2665 // If the exception contains an output token, 2666 // it should be sent to the acceptor. 2667 byte[] outTok = e.getOutputToken(); 2668 if (outTok != null) { 2669 sendToken(outTok); 2670 } 2671 } 2672 2674 6.4.5. acceptSecContext 2676 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2677 throws GSSException 2679 Called by the context acceptor upon receiving a token from the peer. 2681 This method may return an output token that the application will need 2682 to send to the peer for further processing by the init call. 2684 The "null" return value indicates that no token needs to be sent to 2685 the peer. The application can call isEstablished() to determine if 2686 the context establishment phase is complete for this peer. A return 2687 value of "false" from isEstablished() indicates that more tokens are 2688 expected to be supplied to this method. 2690 Note that it is possible that acceptSecContext() will return a token 2691 for the peer and isEstablished() will return "true" also. This 2692 indicates that the token needs to be sent to the peer, but the local 2693 end of the context is now fully established. 2695 Upon completion of the context establishment, the available context 2696 options may be queried through the get methods. 2698 A GSSException will be thrown if the call fails. Users should call 2699 its getOutputToken() method to find out if there is a token that can 2700 be sent to the initiator to communicate the reason for the error. 2702 Parameters: 2704 inTok Token generated by the peer. 2706 offset The offset within the inTok where the token 2707 begins. 2709 len The length of the token within the inTok 2710 (starting at the offset). 2712 6.4.6. Example Code 2713 2714 // acquire server credentials 2715 GSSCredential server = mgr.createCredential(...); 2717 // create acceptor GSS-API context from the default provider 2718 GSSContext context = mgr.createContext(server, null); 2720 try { 2721 do { 2722 byte[] inTok = readToken(); 2724 byte[] outTok = context.acceptSecContext(inTok, 0, 2725 inTok.length); 2727 // possibly send token to peer 2728 if (outTok != null) 2729 sendToken(outTok); 2731 // check if local context establishment is complete 2732 if (context.isEstablished()) 2733 break; 2734 } while (true); 2736 } catch (GSSException e) { 2737 print("GSS-API error: " + e.getMessage()); 2739 // If the exception contains an output token, 2740 // it should be sent to the initiator. 2741 byte[] outTok = e.getOutputToken(); 2742 if (outTok != null) { 2743 sendToken(outTok); 2744 } 2745 } 2746 2748 6.4.7. isEstablished 2750 public boolean isEstablished() 2752 Used during context establishment to determine the state of the 2753 context. Returns "true" if this is a fully established context on 2754 the caller's side and no more tokens are needed from the peer. 2755 Should be called after a call to initSecContext() or 2756 acceptSecContext() when no GSSException is thrown. 2758 6.4.8. dispose 2760 public void dispose() throws GSSException 2762 Releases any system resources and cryptographic information stored in 2763 the context object. This will invalidate the context. 2765 6.4.9. getWrapSizeLimit 2767 public int getWrapSizeLimit(int qop, boolean confReq, 2768 int maxTokenSize) throws GSSException 2770 Returns the maximum message size that, if presented to the wrap 2771 method with the same confReq and qop parameters, will result in an 2772 output token containing no more than the maxTokenSize bytes. 2774 This call is intended for use by applications that communicate over 2775 protocols that impose a maximum message size. It enables the 2776 application to fragment messages prior to applying protection. 2778 GSS-API implementations are recommended but not required to detect 2779 invalid QOP values when getWrapSizeLimit is called. This routine 2780 guarantees only a maximum message size, not the availability of 2781 specific QOP values for message protection. 2783 Successful completion of this call does not guarantee that wrap will 2784 be able to protect a message of the computed length, since this 2785 ability may depend on the availability of system resources at the 2786 time that wrap is called. However, if the implementation itself 2787 imposes an upper limit on the length of messages that may be 2788 processed by wrap, the implementation should not return a value that 2789 is greater than this length. 2791 Parameters: 2793 qop Indicates the level of protection wrap will be 2794 asked to provide. 2796 confReq Indicates if wrap will be asked to provide 2797 privacy service. 2799 maxTokenSize The desired maximum size of the token emitted by 2800 wrap. 2802 6.4.10. wrap 2804 public byte[] wrap(byte[] inBuf, int offset, int len, 2805 MessageProp msgProp) throws GSSException 2807 Applies per-message security services over the established security 2808 context. The method will return a token with a cryptographic MIC and 2809 may optionally encrypt the specified inBuf. The returned byte array 2810 will contain both the MIC and the message. 2812 The MessageProp object is instantiated by the application and used to 2813 specify a QOP value that selects cryptographic algorithms, and a 2814 privacy service to optionally encrypt the message. The underlying 2815 mechanism that is used in the call may not be able to provide the 2816 privacy service. It sets the actual privacy service that it does 2817 provide in this MessageProp object, which the caller should then 2818 query upon return. If the mechanism is not able to provide the 2819 requested QOP, it throws a GSSException with the BAD_QOP code. 2821 Since some application-level protocols may wish to use tokens emitted 2822 by wrap to provide "secure framing", implementations should support 2823 the wrapping of zero-length messages. 2825 The application will be responsible for sending the token to the 2826 peer. 2828 Parameters: 2830 inBuf Application data to be protected. 2832 offset The offset within the inBuf where the data 2833 begins. 2835 len The length of the data within the inBuf (starting 2836 at the offset). 2838 msgProp Instance of MessageProp that is used by the 2839 application to set the desired QOP and privacy 2840 state. Set the desired QOP to 0 to request the 2841 default QOP. Upon return from this method, this 2842 object will contain the actual privacy state that 2843 was applied to the message by the underlying 2844 mechanism. 2846 6.4.11. unwrap 2848 public byte[] unwrap(byte[] inBuf, int offset, int len, 2849 MessageProp msgProp) throws GSSException 2851 Used by the peer application to process tokens generated with the 2852 wrap call. The method will return the message supplied in the peer 2853 application to the wrap call, verifying the embedded MIC. 2855 The MessageProp object is instantiated by the application and is used 2856 by the underlying mechanism to return information to the caller such 2857 as the QOP, whether confidentiality was applied to the message, and 2858 other supplementary message state information. 2860 Since some application-level protocols may wish to use tokens emitted 2861 by wrap to provide "secure framing", implementations should support 2862 the wrapping and unwrapping of zero-length messages. 2864 Parameters: 2866 inBuf GSS-API wrap token received from peer. 2868 offset The offset within the inBuf where the token 2869 begins. 2871 len The length of the token within the inBuf 2872 (starting at the offset). 2874 msgProp Upon return from the method, this object will 2875 contain the applied QOP, the privacy state of the 2876 message, and supplementary information, described 2877 in section 4.12.3, stating whether the token was 2878 a duplicate, old, out of sequence, or arriving 2879 after a gap. 2881 6.4.12. getMIC 2883 public byte[] getMIC(byte[] inMsg, int offset, int len, 2884 MessageProp msgProp) throws GSSException 2886 Returns a token containing a cryptographic MIC for the supplied 2887 message for transfer to the peer application. Unlike wrap, which 2888 encapsulates the user message in the returned token, only the message 2889 MIC is returned in the output token. 2891 Note that privacy can only be applied through the wrap call. 2893 Since some application-level protocols may wish to use tokens emitted 2894 by getMIC to provide "secure framing", implementations should support 2895 derivation of MICs from zero-length messages. 2897 Parameters: 2899 inMsg Message over which to generate MIC. 2901 offset The offset within the inMsg where the token 2902 begins. 2904 len The length of the token within the inMsg 2905 (starting at the offset). 2907 msgProp Instance of MessageProp that is used by the 2908 application to set the desired QOP. Set the 2909 desired QOP to 0 in msgProp to request the 2910 default QOP. Alternatively, pass in "null" for 2911 msgProp to request default QOP. 2913 6.4.13. verifyMIC 2915 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 2916 byte[] inMsg, int msgOffset, int msgLen, 2917 MessageProp msgProp) throws GSSException 2919 Verifies the cryptographic MIC, contained in the token parameter, 2920 over the supplied message. 2922 The MessageProp object is instantiated by the application and is used 2923 by the underlying mechanism to return information to the caller such 2924 as the QOP indicating the strength of protection that was applied to 2925 the message and other supplementary message state information. 2927 Since some application-level protocols may wish to use tokens emitted 2928 by getMIC to provide "secure framing", implementations should support 2929 the calculation and verification of MICs over zero-length messages. 2931 Parameters: 2933 inTok Token generated by peer's getMIC method. 2935 tokOffset The offset within the inTok where the token 2936 begins. 2938 tokLen The length of the token within the inTok 2939 (starting at the offset). 2941 inMsg Application message over which to verify the 2942 cryptographic MIC. 2944 msgOffset The offset within the inMsg where the message 2945 begins. 2947 msgLen The length of the message within the inMsg 2948 (starting at the offset). 2950 msgProp Upon return from the method, this object will 2951 contain the applied QOP and supplementary 2952 information, described in section 4.12.3, stating 2953 whether the token was a duplicate, old, out of 2954 sequence, or arriving after a gap. The 2955 confidentiality state will be set to "false". 2957 6.4.14. export 2959 public byte[] export() throws GSSException 2961 Provided to support the sharing of work between multiple processes. 2962 This routine will typically be used by the context acceptor, in an 2963 application where a single process receives incoming connection 2964 requests and accepts security contexts over them, then passes the 2965 established context to one or more other processes for message 2966 exchange. 2968 This method deactivates the security context and creates an inter- 2969 process token which, when passed to the byte array constructor of the 2970 GSSContext interface in another process, will re-activate the context 2971 in the second process. Only a single instantiation of a given 2972 context may be active at any one time; a subsequent attempt by a 2973 context exporter to access the exported security context will fail. 2975 The implementation may constrain the set of processes by which the 2976 inter-process token may be imported, either as a function of local 2977 security policy, or as a result of implementation decisions. For 2978 example, some implementations may constrain contexts to be passed 2979 only between processes that run under the same account, or which are 2980 part of the same process group. 2982 The inter-process token may contain security-sensitive information 2983 (for example, cryptographic keys). While mechanisms are encouraged 2984 to either avoid placing such sensitive information within inter- 2985 process tokens or to encrypt the token before returning it to the 2986 application, in a typical GSS-API implementation, this may not be 2987 possible. Thus, the application must take care to protect the inter- 2988 process token, and ensure that any process to which the token is 2989 transferred is trustworthy. 2991 6.4.15. requestMutualAuth 2993 public void requestMutualAuth(boolean state) throws GSSException 2995 Sets the request state of the mutual authentication flag for the 2996 context. This method is only valid before the context creation 2997 process begins and only for the initiator. 2999 Parameters: 3001 state Boolean representing if mutual authentication 3002 should be requested during context establishment. 3004 6.4.16. requestReplayDet 3006 public void requestReplayDet(boolean state) throws GSSException 3008 Sets the request state of the replay detection service for the 3009 context. This method is only valid before the context creation 3010 process begins and only for the initiator. 3012 Parameters: 3014 state Boolean representing if replay detection is 3015 desired over the established context. 3017 6.4.17. requestSequenceDet 3019 public void requestSequenceDet(boolean state) throws GSSException 3021 Sets the request state for the sequence checking service of the 3022 context. This method is only valid before the context creation 3023 process begins and only for the initiator. 3025 Parameters: 3027 state Boolean representing if sequence detection is 3028 desired over the established context. 3030 6.4.18. requestCredDeleg 3032 public void requestCredDeleg(boolean state) throws GSSException 3033 Sets the request state for the credential delegation flag for the 3034 context. This method is only valid before the context creation 3035 process begins and only for the initiator. 3037 Parameters: 3039 state Boolean representing if credential delegation is 3040 desired. 3042 6.4.19. requestAnonymity 3044 public void requestAnonymity(boolean state) throws GSSException 3046 Requests anonymous support over the context. This method is only 3047 valid before the context creation process begins and only for the 3048 initiator. 3050 Parameters: 3052 state Boolean representing if anonymity support is 3053 requested. 3055 6.4.20. requestConf 3057 public void requestConf(boolean state) throws GSSException 3059 Requests that confidentiality service be available over the context. 3060 This method is only valid before the context creation process begins 3061 and only for the initiator. 3063 Parameters: 3065 state Boolean indicating if confidentiality services 3066 are to be requested for the context. 3068 6.4.21. requestInteg 3070 public void requestInteg(boolean state) throws GSSException 3072 Requests that integrity services be available over the context. This 3073 method is only valid before the context creation process begins and 3074 only for the initiator. 3076 Parameters: 3078 state Boolean indicating if integrity services are to 3079 be requested for the context. 3081 6.4.22. requestLifetime 3083 public void requestLifetime(int lifetime) throws GSSException 3085 Sets the desired lifetime for the context in seconds. This method is 3086 only valid before the context creation process begins and only for 3087 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 3088 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 3089 lifetime. 3091 Parameters: 3093 lifetime The desired context lifetime in seconds. 3095 6.4.23. setChannelBinding 3097 public void setChannelBinding(ChannelBinding cb) throws GSSException 3099 Sets the channel bindings to be used during context establishment. 3100 This method is only valid before the context creation process begins. 3102 Parameters: 3104 cb Channel bindings to be used. 3106 6.4.24. getCredDelegState 3108 public boolean getCredDelegState() 3110 Returns the state of the delegated credentials for the context. When 3111 issued before context establishment is completed or when the 3112 isProtReady method returns "false", it returns the desired state; 3113 otherwise, it will indicate the actual state over the established 3114 context. 3116 6.4.25. getMutualAuthState 3118 public boolean getMutualAuthState() 3120 Returns the state of the mutual authentication option for the 3121 context. When issued before context establishment completes or when 3122 the isProtReady method returns "false", it returns the desired state; 3123 otherwise, it will indicate the actual state over the established 3124 context. 3126 6.4.26. getReplayDetState 3128 public boolean getReplayDetState() 3130 Returns the state of the replay detection option for the context. 3131 When issued before context establishment completes or when the 3132 isProtReady method returns "false", it returns the desired state; 3133 otherwise, it will indicate the actual state over the established 3134 context. 3136 6.4.27. getSequenceDetState 3138 public boolean getSequenceDetState() 3140 Returns the state of the sequence detection option for the context. 3141 When issued before context establishment completes or when the 3142 isProtReady method returns "false", it returns the desired state; 3143 otherwise, it will indicate the actual state over the established 3144 context. 3146 6.4.28. getAnonymityState 3148 public boolean getAnonymityState() 3150 Returns "true" if this is an anonymous context. When issued before 3151 context establishment completes or when the isProtReady method 3152 returns "false", it returns the desired state; otherwise, it will 3153 indicate the actual state over the established context. 3155 6.4.29. isTransferable 3157 public boolean isTransferable() throws GSSException 3159 Returns "true" if the context is transferable to other processes 3160 through the use of the export method. This call is only valid on 3161 fully established contexts. 3163 6.4.30. isProtReady 3165 public boolean isProtReady() 3167 Returns "true" if the per-message operations can be applied over the 3168 context. Some mechanisms may allow the usage of per-message 3169 operations before the context is fully established. This will also 3170 indicate that the get methods will return actual context state 3171 characteristics instead of the desired ones. 3173 6.4.31. getConfState 3175 public boolean getConfState() 3177 Returns the confidentiality service state over the context. When 3178 issued before context establishment completes or when the isProtReady 3179 method returns "false", it returns the desired state; otherwise, it 3180 will indicate the actual state over the established context. 3182 6.4.32. getIntegState 3184 public boolean getIntegState() 3186 Returns the integrity service state over the context. When issued 3187 before context establishment completes or when the isProtReady method 3188 returns "false", it returns the desired state; otherwise, it will 3189 indicate the actual state over the established context. 3191 6.4.33. getLifetime 3193 public int getLifetime() 3195 Returns the context lifetime in seconds. When issued before context 3196 establishment completes or when the isProtReady method returns 3197 "false", it returns the desired lifetime; otherwise, it will indicate 3198 the remaining lifetime for the context. 3200 6.4.34. getSrcName 3202 public GSSName getSrcName() throws GSSException 3204 Returns the name of the context initiator. This call is valid only 3205 after the context is fully established or the isProtReady method 3206 returns "true". It is guaranteed to return an MN. 3208 6.4.35. getTargName 3210 public GSSName getTargName() throws GSSException 3212 Returns the name of the context target (acceptor). This call is 3213 valid only after the context is fully established or the isProtReady 3214 method returns "true". It is guaranteed to return an MN. 3216 6.4.36. getMech 3218 public Oid getMech() throws GSSException 3219 Returns the mechanism oid for this context. This method may be 3220 called before the context is fully established, but the mechanism 3221 returned may change on successive calls in negotiated mechanism case. 3223 6.4.37. getDelegCred 3225 public GSSCredential getDelegCred() throws GSSException 3227 Returns the delegated credential object on the acceptor's side. To 3228 check for availability of delegated credentials call 3229 getDelegCredState. This call is only valid on fully established 3230 contexts. 3232 6.4.38. isInitiator 3234 public boolean isInitiator() throws GSSException 3236 Returns "true" if this is the initiator of the context. This call is 3237 only valid after the context creation process has started. 3239 6.5. public class MessageProp 3241 This is a utility class used within the per-message GSSContext 3242 methods to convey per-message properties. 3244 When used with the GSSContext interface's wrap and getMIC methods, an 3245 instance of this class is used to indicate the desired QOP and to 3246 request if confidentiality services are to be applied to caller 3247 supplied data (wrap only). To request default QOP, the value of 0 3248 should be used for QOP. 3250 When used with the unwrap and verifyMIC methods of the GSSContext 3251 interface, an instance of this class will be used to indicate the 3252 applied QOP and confidentiality services over the supplied message. 3253 In the case of verifyMIC, the confidentiality state will always be 3254 "false". Upon return from these methods, this object will also 3255 contain any supplementary status values applicable to the processed 3256 token. The supplementary status values can indicate old tokens, out 3257 of sequence tokens, gap tokens, or duplicate tokens. 3259 6.5.1. Constructors 3261 public MessageProp(boolean privState) 3263 Constructor that sets QOP to 0 indicating that the default QOP is 3264 requested. 3266 Parameters: 3268 privState The desired privacy state. "true" for privacy and 3269 "false" for integrity only. 3271 public MessageProp(int qop, boolean privState) 3273 Constructor that sets the values for the qop and privacy state. 3275 Parameters: 3277 qop The desired QOP. Use 0 to request a default QOP. 3279 privState The desired privacy state. "true" for privacy and 3280 "false" for integrity only. 3282 6.5.2. getQOP 3284 public int getQOP() 3286 Retrieves the QOP value. 3288 6.5.3. getPrivacy 3290 public boolean getPrivacy() 3292 Retrieves the privacy state. 3294 6.5.4. getMinorStatus 3296 public int getMinorStatus() 3298 Retrieves the minor status that the underlying mechanism might have 3299 set. 3301 6.5.5. getMinorString 3303 public String getMinorString() 3305 Returns a string explaining the mechanism-specific error code. "null" 3306 will be returned when no mechanism error code has been set. 3308 6.5.6. setQOP 3310 public void setQOP(int qopVal) 3312 Sets the QOP value. 3314 Parameters: 3316 qopVal The QOP value to be set. Use 0 to request a 3317 default QOP value. 3319 6.5.7. setPrivacy 3321 public void setPrivacy(boolean privState) 3323 Sets the privacy state. 3325 Parameters: 3327 privState The privacy state to set. 3329 6.5.8. isDuplicateToken 3331 public boolean isDuplicateToken() 3333 Returns "true" if this is a duplicate of an earlier token. 3335 6.5.9. isOldToken 3337 public boolean isOldToken() 3339 Returns "true" if the token's validity period has expired. 3341 6.5.10. isUnseqToken 3343 public boolean isUnseqToken() 3345 Returns "true" if a later token has already been processed. 3347 6.5.11. isGapToken 3349 public boolean isGapToken() 3351 Returns "true" if an expected per-message token was not received. 3353 6.5.12. setSupplementaryStates 3355 public void setSupplementaryStates(boolean duplicate, 3356 boolean old, boolean unseq, boolean gap, 3357 int minorStatus, String minorString) 3359 This method sets the state for the supplementary information flags 3360 and the minor status in MessageProp. It is not used by the 3361 application but by the GSS implementation to return this information 3362 to the caller of a per-message context method. 3364 Parameters: 3366 duplicate "true" if the token was a duplicate of an earlier 3367 token; otherwise, "false". 3369 old "true" if the token's validity period has 3370 expired; otherwise, "false". 3372 unseq "true" if a later token has already been 3373 processed; otherwise, "false". 3375 gap "true" if one or more predecessor tokens have not 3376 yet been successfully processed; otherwise, 3377 "false". 3379 minorStatus The integer minor status code that the underlying 3380 mechanism wants to set. 3382 minorString The textual representation of the minorStatus 3383 value. 3385 6.6. public class ChannelBinding 3387 The GSS-API accommodates the concept of caller-provided channel 3388 binding information. Channel bindings are used to strengthen the 3389 quality with which peer entity authentication is provided during 3390 context establishment. They enable the GSS-API callers to bind the 3391 establishment of the security context to relevant characteristics 3392 like addresses or to application-specific data. 3394 The caller initiating the security context must determine the 3395 appropriate channel binding values to set in the GSSContext object. 3396 The acceptor must provide an identical binding in order to validate 3397 that received tokens possess correct channel-related characteristics. 3399 Use of channel bindings is optional in GSS-API. Since channel- 3400 binding information may be transmitted in context establishment 3401 tokens, applications should therefore not use confidential data as 3402 channel-binding components. 3404 6.6.1. Constructors 3406 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3407 byte[] appData) 3409 Create a ChannelBinding object with user-supplied address information 3410 and data. "null" values can be used for any fields that the 3411 application does not want to specify. 3413 Parameters: 3415 initAddr The address of the context initiator. "null" 3416 value can be supplied to indicate that the 3417 application does not want to set this value. 3419 acceptAddr The address of the context acceptor. "null" value 3420 can be supplied to indicate that the application 3421 does not want to set this value. 3423 appData Application-supplied data to be used as part of 3424 the channel bindings. "null" value can be 3425 supplied to indicate that the application does 3426 not want to set this value. 3428 public ChannelBinding(byte[] appData) 3430 Creates a ChannelBinding object without any addressing information. 3432 Parameters: 3434 appData Application supplied data to be used as part of 3435 the channel bindings. 3437 6.6.2. getInitiatorAddress 3439 public InetAddress getInitiatorAddress() 3441 Returns the initiator's address for this channel binding. "null" is 3442 returned if the address has not been set. 3444 6.6.3. getAcceptorAddress 3446 public InetAddress getAcceptorAddress() 3448 Returns the acceptor's address for this channel binding. "null" is 3449 returned if the address has not been set. 3451 6.6.4. getApplicationData 3453 public byte[] getApplicationData() 3455 Returns application data being used as part of the ChannelBinding. 3456 "null" is returned if no application data has been specified for the 3457 channel binding. 3459 6.6.5. equals 3461 public boolean equals(Object obj) 3463 Returns "true" if two channel bindings match. (Note that the Java 3464 language specification requires that two objects that are equal 3465 according to the equals(Object) method must return the same integer 3466 result when the hashCode() method is called on them.) 3468 Parameters: 3470 obj Another channel binding with which to compare. 3472 6.7. public class Oid 3474 This class represents Universal Object Identifiers (Oids) and their 3475 associated operations. 3477 Oids are hierarchically globally interpretable identifiers used 3478 within the GSS-API framework to identify mechanisms and name formats. 3480 The structure and encoding of Oids is defined in ISOIEC-8824 and 3481 ISOIEC-8825. For example, the Oid representation of the Kerberos v5 3482 mechanism is "1.2.840.113554.1.2.2". 3484 The GSSName name class contains public static Oid objects 3485 representing the standard name types defined in GSS-API. 3487 6.7.1. Constructors 3489 public Oid(String strOid) throws GSSException 3491 Creates an Oid object from a string representation of its integer 3492 components (e.g., "1.2.840.113554.1.2.2"). 3494 Parameters: 3496 strOid The string representation for the oid. 3498 public Oid(InputStream derOid) throws GSSException 3500 Creates an Oid object from its DER encoding. This refers to the full 3501 encoding including tag and length. The structure and encoding of 3502 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3503 identical in functionality to its byte array counterpart. 3505 Parameters: 3507 derOid Stream containing the DER-encoded oid. 3509 public Oid(byte[] DEROid) throws GSSException 3511 Creates an Oid object from its DER encoding. This refers to the full 3512 encoding including tag and length. The structure and encoding of 3513 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3514 identical in functionality to its byte array counterpart. 3516 Parameters: 3518 derOid Byte array storing a DER-encoded oid. 3520 6.7.2. toString 3522 public String toString() 3524 Returns a string representation of the oid's integer components in 3525 dot separated notation (e.g., "1.2.840.113554.1.2.2"). 3527 6.7.3. equals 3529 public boolean equals(Object Obj) 3531 Returns "true" if the two Oid objects represent the same oid value. 3532 (Note that the Java language specification [JLS] requires that two 3533 objects that are equal according to the equals(Object) method must 3534 return the same integer result when the hashCode() method is called 3535 on them.) 3537 Parameters: 3539 obj Another Oid object with which to compare. 3541 6.7.4. getDER 3543 public byte[] getDER() 3545 Returns the full ASN.1 DER encoding for this oid object, which 3546 includes the tag and length. 3548 6.7.5. containedIn 3550 public boolean containedIn(Oid[] oids) 3552 A utility method to test if an Oid object is contained within the 3553 supplied Oid object array. 3555 Parameters: 3557 oids An array of oids to search. 3559 6.8. public class GSSException extends Exception 3561 This exception is thrown whenever a fatal GSS-API error occurs 3562 including mechanism-specific errors. It may contain both, the major 3563 and minor, GSS-API status codes. The mechanism implementors are 3564 responsible for setting appropriate minor status codes when throwing 3565 this exception. Aside from delivering the numeric error code(s) to 3566 the caller, this class performs the mapping from their numeric values 3567 to textual representations. This exception may also include an 3568 output token that should be sent to the peer. For example, when an 3569 initSecContext call fails due to a fatal error, the mechanism may 3570 define an error token that should be sent to the peer for debugging 3571 or informational purpose. All Java GSS-API methods are declared 3572 throwing this exception. 3574 All implementations are encouraged to use the Java 3575 internationalization techniques to provide local translations of the 3576 message strings. 3578 6.8.1. Static Constants 3580 All valid major GSS-API error code values are declared as constants 3581 in this class. 3583 public static final int BAD_BINDINGS 3585 Channel bindings mismatch error. The value of this constant is 1. 3587 public static final int BAD_MECH 3589 Unsupported mechanism requested error. The value of this constant is 3590 2. 3592 public static final int BAD_NAME 3594 Invalid name provided error. The value of this constant is 3. 3596 public static final int BAD_NAMETYPE 3598 Name of unsupported type provided error. The value of this constant 3599 is 4. 3601 public static final int BAD_STATUS 3602 Invalid status code error - this is the default status value. The 3603 value of this constant is 5. 3605 public static final int BAD_MIC 3607 Token had invalid integrity check error. The value of this constant 3608 is 6. 3610 public static final int CONTEXT_EXPIRED 3612 Specified security context expired error. The value of this constant 3613 is 7. 3615 public static final int CREDENTIALS_EXPIRED 3617 Expired credentials detected error. The value of this constant is 8. 3619 public static final int DEFECTIVE_CREDENTIAL 3621 Defective credential error. The value of this constant is 9. 3623 public static final int DEFECTIVE_TOKEN 3625 Defective token error. The value of this constant is 10. 3627 public static final int FAILURE 3629 General failure, unspecified at GSS-API level. The value of this 3630 constant is 11. 3632 public static final int NO_CONTEXT 3634 Invalid security context error. The value of this constant is 12. 3636 public static final int NO_CRED 3638 Invalid credentials error. The value of this constant is 13. 3640 public static final int BAD_QOP 3642 Unsupported QOP value error. The value of this constant is 14. 3644 public static final int UNAUTHORIZED 3646 Operation unauthorized error. The value of this constant is 15. 3648 public static final int UNAVAILABLE 3649 Operation unavailable error. The value of this constant is 16. 3651 public static final int DUPLICATE_ELEMENT 3653 Duplicate credential element requested error. The value of this 3654 constant is 17. 3656 public static final int NAME_NOT_MN 3658 Name contains multi-mechanism elements error. The value of this 3659 constant is 18. 3661 public static final int DUPLICATE_TOKEN 3663 The token was a duplicate of an earlier token. This is contained in 3664 an exception only when detected during context establishment, in 3665 which case it is considered a fatal error. (Non-fatal supplementary 3666 codes are indicated via the MessageProp object.) The value of this 3667 constant is 19. 3669 public static final int OLD_TOKEN 3671 The token's validity period has expired. This is contained in an 3672 exception only when detected during context establishment, in which 3673 case it is considered a fatal error. (Non-fatal supplementary codes 3674 are indicated via the MessageProp object.) The value of this 3675 constant is 20. 3677 public static final int UNSEQ_TOKEN 3679 A later token has already been processed. This is contained in an 3680 exception only when detected during context establishment, in which 3681 case it is considered a fatal error. (Non-fatal supplementary codes 3682 are indicated via the MessageProp object.) The value of this 3683 constant is 21. 3685 public static final int GAP_TOKEN 3687 An expected per-message token was not received. This is contained in 3688 an exception only when detected during context establishment, in 3689 which case it is considered a fatal error. (Non-fatal supplementary 3690 codes are indicated via the MessageProp object.) The value of this 3691 constant is 22. 3693 6.8.2. Constructors 3695 public GSSException(int majorCode) 3697 Creates a GSSException object with a specified major code. 3699 Calling this constructor is equivalent to calling 3700 GSSException(majorCode, null, 0, null, null). 3702 public GSSException(int majorCode, int minorCode, String minorString) 3704 Creates a GSSException object with the specified major code, minor 3705 code, and minor code textual explanation. This constructor is to be 3706 used when the exception is originating from the security mechanism. 3707 It allows to specify the GSS code and the mechanism code. 3709 Calling this constructor is equivalent to calling 3710 GSSException(majorCode, null, minorCode, minorString, null). 3712 public GSSException(int majorCode, String majorString, 3713 int minorCode, String minorString, 3714 byte[] outputToken) 3716 Creates a GSSException object with the specified major code, major 3717 code textual explanation, minor code, minor code textual explanation, 3718 and an output token. This is a general-purpose constructor that can 3719 be used to create any type of GSSException. 3721 Parameters: 3723 majorCode The GSS error code causing this exception to be 3724 thrown. 3726 majorString The textual explanation of the GSS error code. 3727 If null is provided, a default explanation that 3728 matches the majorCode will be set. 3730 minorCode The mechanism error code causing this exception 3731 to be thrown. Can be 0 if no mechanism error 3732 code is available. 3734 minorString The textual explanation of the mechanism error 3735 code. Can be null if no textual explanation is 3736 available. 3738 outputToken The output token that should be sent to the peer. 3739 Can be null if no such token is available. It 3740 must not be an empty array. When provided, the 3741 array will be cloned to protect against 3742 subsequent modifications. 3744 6.8.3. getMajor 3746 public int getMajor() 3748 Returns the major code representing the GSS error code that caused 3749 this exception to be thrown. 3751 6.8.4. getMinor 3753 public int getMinor() 3755 Returns the mechanism error code that caused this exception. The 3756 minor code is set by the underlying mechanism. Value of 0 indicates 3757 that mechanism error code is not set. 3759 6.8.5. getMajorString 3761 public String getMajorString() 3763 Returns a string explaining the GSS major error code causing this 3764 exception to be thrown. 3766 6.8.6. getMinorString 3768 public String getMinorString() 3770 Returns a string explaining the mechanism-specific error code. "null" 3771 will be returned when no string explaining the mechanism error code 3772 has been set. 3774 6.8.7. getOutputToken 3776 public byte[] getOutputToken 3778 Returns the output token in a new byte array. 3780 If the method (For example, GSSContext#initSecContext) that throws 3781 this GSSException needs to generate an output token that should be 3782 sent to the peer, that token will be stored in this GSSException and 3783 can be retrieved with this method. 3785 The return value must be null if no such token is generated. It must 3786 not be an empty byte array. 3788 6.8.8. setMinor 3790 public void setMinor(int minorCode, String message) 3792 Used internally by the GSS-API implementation and the underlying 3793 mechanisms to set the minor code and its textual representation. 3795 Parameters: 3797 minorCode The mechanism-specific error code. 3799 message A textual explanation of the mechanism error 3800 code. 3802 6.8.9. toString 3804 public String toString() 3806 Returns a textual representation of both the major and minor status 3807 codes. 3809 6.8.10. getMessage 3811 public String getMessage() 3813 Returns a detailed message of this exception. Overrides 3814 Throwable.getMessage. It is customary in Java to use this method to 3815 obtain exception information. 3817 7. Sample Applications 3819 7.1. Simple GSS Context Initiator 3821 3822 import org.ietf.jgss.*; 3824 /** 3825 * This is a partial sketch for a simple client program that acts 3826 * as a GSS context initiator. It illustrates how to use the Java 3827 * bindings for the GSS-API specified in 3828 * Generic Security Service API Version 2 : Java bindings 3829 * 3830 * 3831 * This code sketch assumes the existence of a GSS-API 3832 * implementation that supports the mechanism that it will need 3833 * and is present as a library package (org.ietf.jgss) either as 3834 * part of the standard JRE or in the CLASSPATH the application 3835 * specifies. 3837 */ 3839 public class SimpleClient { 3841 private String serviceName; // name of peer (i.e., server) 3842 private GSSCredential clientCred = null; 3843 private GSSContext context = null; 3844 private Oid mech; // underlying mechanism to use 3846 private GSSManager mgr = GSSManager.getInstance(); 3848 ... 3849 ... 3851 private void clientActions() { 3852 initializeGSS(); 3853 establishContext(); 3854 doCommunication(); 3855 } 3857 /** 3858 * Acquire credentials for the client. 3859 */ 3860 private void initializeGSS() { 3862 try { 3864 clientCred = mgr.createCredential(null /*default princ*/, 3865 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 3866 mech /* mechanism to use */, 3867 GSSCredential.INITIATE_ONLY /* init context */); 3869 print("GSSCredential created for " + 3870 cred.getName().toString()); 3871 print("Credential lifetime (sec)=" + 3872 cred.getRemainingLifetime()); 3873 } catch (GSSException e) { 3874 print("GSS-API error in credential acquisition: " 3875 + e.getMessage()); 3876 ... 3877 ... 3878 } 3879 ... 3880 ... 3881 } 3883 /** 3884 * Does the security context establishment with the 3885 * server. 3886 */ 3887 private void establishContext() { 3889 byte[] inToken = new byte[0]; 3890 byte[] outToken = null; 3892 try { 3894 GSSName peer = mgr.createName(serviceName, 3895 GSSName.NT_HOSTBASED_SERVICE); 3896 context = mgr.createContext(peer, mech, gssCred, 3897 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 3899 // Will need to support confidentiality 3900 context.requestConf(true); 3902 while (!context.isEstablished()) { 3904 outToken = context.initSecContext(inToken, 0, 3905 inToken.length); 3907 if (outToken != null) 3908 writeGSSToken(outToken); 3910 if (!context.isEstablished()) 3911 inToken = readGSSToken(); 3912 } 3914 GSSName peer = context.getSrcName(); 3915 print("Security context established with " + peer + 3916 " using underlying mechanism " + mech.toString()); 3917 } catch (GSSException e) { 3918 print("GSS-API error during context establishment: " 3919 + e.getMessage()); 3921 // If the exception contains an output token, 3922 // it should be sent to the acceptor. 3923 byte[] outTok = e.getOutputToken(); 3924 if (outTok != null) { 3925 writeGSSToken(outTok); 3926 } 3927 ... 3928 ... 3929 } 3930 ... 3931 ... 3932 } 3933 /** 3934 * Sends some data to the server and reads back the 3935 * response. 3936 */ 3937 private void doCommunication() { 3938 byte[] inToken = null; 3939 byte[] outToken = null; 3940 byte[] buffer; 3942 // Container for multiple input-output arguments to and 3943 // from the per-message routines (e.g., wrap/unwrap). 3944 MessageProp messgInfo = new MessageProp(); 3946 try { 3948 /* 3949 * Now send some bytes to the server to be 3950 * processed. They will be integrity protected 3951 * but not encrypted for privacy. 3952 */ 3954 buffer = readFromFile(); 3956 // Set privacy to "false" and use the default QOP 3957 messgInfo.setPrivacy(false); 3959 outToken = context.wrap(buffer, 0, buffer.length, 3960 messgInfo); 3962 writeGSSToken(outToken); 3964 /* 3965 * Now read the response from the server. 3966 */ 3968 inToken = readGSSToken(); 3969 buffer = context.unwrap(inToken, 0, 3970 inToken.length, messgInfo); 3971 // All ok if no exception was thrown! 3973 GSSName peer = context.getSrcName(); 3975 print("Message from " + peer.toString() 3976 + " arrived."); 3977 print("Was it encrypted? " + 3978 messgInfo.getPrivacy()); 3979 print("Duplicate Token? " + 3980 messgInfo.isDuplicateToken()); 3982 print("Old Token? " + 3983 messgInfo.isOldToken()); 3984 print("Unsequenced Token? " + 3985 messgInfo.isUnseqToken()); 3986 print("Gap Token? " + 3987 messgInfo.isGapToken()); 3988 ... 3989 ... 3990 } catch (GSSException e) { 3991 print("GSS-API error in per-message calls: " 3992 + e.getMessage()); 3993 ... 3994 ... 3995 } 3996 ... 3997 ... 3998 } // end of doCommunication method 4000 ... 4001 ... 4003 } // end of class SimpleClient 4004 4006 7.2. Simple GSS Context Acceptor 4008 4009 import org.ietf.jgss.*; 4011 /** 4012 * This is a partial sketch for a simple server program that acts 4013 * as a GSS context acceptor. It illustrates how to use the Java 4014 * bindings for the GSS-API specified in 4015 * Generic Security Service API Version 2 : Java bindings. 4016 * 4017 * This code sketch assumes the existence of a GSS-API 4018 * implementation that supports the mechanisms that it will need 4019 * and is present as a library package (org.ietf.jgss) either as 4020 * part of the standard JRE or in the CLASSPATH the application 4021 * specifies. 4022 */ 4024 import org.ietf.jgss.*; 4026 public class SimpleServer { 4028 private String serviceName; 4029 private GSSName name; 4030 private GSSCredential cred; 4032 private GSSManager mgr; 4034 ... 4035 ... 4037 /** 4038 * Wait for client connections, establish security contexts 4039 * and provide service. 4040 */ 4041 private void loop() { 4042 ... 4043 ... 4044 mgr = GSSManager.getInstance(); 4046 name = mgr.createName(serviceName, 4047 GSSName.NT_HOSTBASED_SERVICE); 4049 cred = mgr.createCredential(name, 4050 GSSCredential.INDEFINITE_LIFETIME, 4051 null, 4052 GSSCredential.ACCEPT_ONLY); 4054 // Loop infinitely 4055 while (true) { 4056 Socket s = serverSock.accept(); 4058 // Start a new thread to serve this connection 4059 Thread serverThread = new ServerThread(s); 4060 serverThread.start(); 4061 } 4062 } 4064 /** 4065 * Inner class ServerThread whose run() method provides the 4066 * secure service to a connection. 4067 */ 4069 private class ServerThread extends Thread { 4071 ... 4072 ... 4074 /** 4075 * Deals with the connection from one client. It also 4076 * handles all GSSException's thrown while talking to 4077 * this client. 4079 */ 4080 public void run() { 4082 byte[] inToken = null; 4083 byte[] outToken = null; 4084 byte[] buffer; 4086 GSSName peer; 4088 // Container for multiple input-output arguments to 4089 // and from the per-message routines 4090 // (i.e., wrap/unwrap). 4091 MessageProp supplInfo = new MessageProp(); 4092 GSSContext secContext = null; 4094 try { 4095 // Now do the context establishment loop 4096 GSSContext context = mgr.createContext(cred); 4098 while (!context.isEstablished()) { 4100 inToken = readGSSToken(); 4101 outToken = context.acceptSecContext(inToken, 4102 0, inToken.length); 4103 if (outToken != null) 4104 writeGSSToken(outToken); 4105 } 4107 // SimpleServer wants confidentiality to be 4108 // available. Check for it. 4109 if (!context.getConfState()){ 4110 ... 4111 ... 4112 } 4114 GSSName peer = context.getSrcName(); 4115 Oid mech = context.getMech(); 4116 print("Security context established with " + 4117 peer.toString() + 4118 " using underlying mechanism " + 4119 mech.toString() + 4120 " from Provider " + 4121 context.getProvider().getName()); 4123 // Now read the bytes sent by the client to be 4124 // processed. 4125 inToken = readGSSToken(); 4126 // Unwrap the message 4127 buffer = context.unwrap(inToken, 0, 4128 inToken.length, supplInfo); 4129 // All ok if no exception was thrown! 4131 // Print other supplementary per-message status 4132 // information. 4134 print("Message from " + 4135 peer.toString() + " arrived."); 4136 print("Was it encrypted? " + 4137 supplInfo.getPrivacy()); 4138 print("Duplicate Token? " + 4139 supplInfo.isDuplicateToken()); 4140 print("Old Token? " + supplInfo.isOldToken()); 4141 print("Unsequenced Token? " + 4142 supplInfo.isUnseqToken()); 4143 print("Gap Token? " + supplInfo.isGapToken()); 4145 /* 4146 * Now process the bytes and send back an 4147 * encrypted response. 4148 */ 4150 buffer = serverProcess(buffer); 4152 // Encipher it and send it across 4154 supplInfo.setPrivacy(true); // privacy requested 4155 supplInfo.setQOP(0); // default QOP 4156 outToken = context.wrap(buffer, 0, buffer.length, 4157 supplInfo); 4158 writeGSSToken(outToken); 4160 } catch (GSSException e) { 4161 print("GSS-API Error: " + e.getMessage()); 4162 // Alternatively, could call e.getMajorMessage() 4163 // and e.getMinorMessage() 4165 // If the exception contains an output token, 4166 // it should be sent to the initiator. 4167 byte[] outTok = e.getOutputToken(); 4168 if (outTok != null) { 4169 writeGSSToken(outTok); 4170 } 4171 print("Abandoning security context."); 4172 ... 4173 ... 4175 } 4176 ... 4177 ... 4178 } // end of run method in ServerThread 4180 } // end of inner class ServerThread 4182 ... 4183 ... 4185 } // end of class SimpleServer 4186 4188 8. Security Considerations 4190 The Java language security model allows platform providers to have 4191 policy-based fine-grained access control over any resource that an 4192 application wants. When using a Java security manager (such as, but 4193 not limited to, the case of applets running in browsers) the 4194 application code is in a sandbox by default. 4196 Administrators of the platform JRE determine what permissions, if 4197 any, are to be given to source from different codebases. Thus, the 4198 administrator has to be aware of any special requirements that the 4199 GSS provider might have for system resources. For instance, a 4200 Kerberos provider might wish to make a network connection to the Key 4201 Distribution Center (KDC) to obtain initial credentials. This would 4202 not be allowed under the sandbox unless the administrator had granted 4203 permissions for this. Also, note that this granting and checking of 4204 permissions happens transparently to the application and is outside 4205 the scope of this document. 4207 The Java language allows administrators to pre-configure a list of 4208 security service providers in the /lib/security/java.security 4209 file. At runtime, the system approaches these providers in order of 4210 preference when looking for security related services. Applications 4211 have a means to modify this list through methods in the "Security" 4212 class in the "java.security" package. However, since these 4213 modifications would be visible in the entire Java Virtual Machine 4214 (JVM) and thus affect all code executing in it, this operation is not 4215 available in the sandbox and requires special permissions to perform. 4216 Thus, when a GSS application has special needs that are met by a 4217 particular security provider, it has two choices: 4219 1) To install the provider on a JVM-wide basis using the 4220 java.security.Security class and then depend on the system to find 4221 the right provider automatically when the need arises. (This 4222 would require the application to be granted a "insertProvider 4223 SecurityPermission".) 4225 2) To pass an instance of the provider to the local instance of 4226 GSSManager so that only factory calls going through that 4227 GSSManager use the desired provider. (This would not require any 4228 permissions.) 4230 9. IANA Considerations 4232 This document has no actions for IANA. 4234 10. Acknowledgments 4236 This proposed API leverages earlier work performed by the IETF's CAT 4237 WG as outlined in both RFC 2743 [RFC2743] and RFC 2744 [RFC2744]. 4238 Many conceptual definitions, implementation directions, and 4239 explanations have been included from these documents. 4241 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4242 Saltz, and other members of Sun's development team for their helpful 4243 input, comments, and suggestions. 4245 We would also like to thank Joe Salowey, and Michael Smith for many 4246 insightful ideas and suggestions that have contributed to this 4247 document. 4249 11. Changes since RFC 5653 4251 This document has following changes: 4253 1) New error token embedded in GSSException 4255 There is a design flaw in the initSecContext and acceptSecContext 4256 methods of the GSSContext class defined in Generic Security 4257 Service API Version 2: Java Bindings Update [RFC5653]. 4259 The methods could either return a token (possibly null if no more 4260 tokens are needed) when the call succeeds or throw a GSSException 4261 if there is a failure, but NOT both. On the other hand, the C 4262 bindings of GSS-API [RFC2744] can return both, that is to say, a 4263 call to the GSS_Init_sec_context() function can return a major 4264 status code, and at the same time, fill in the output_token 4265 argument if there is one. 4267 Without the ability to emit an error token when there is a 4268 failure, a Java application has no mechanism to tell the other 4269 side what the error is. For example, a "reject" NegTokenResp 4270 token can never be transmitted for the SPNEGO mechanism [RFC4178]. 4272 While a Java method can never return a value and throw an 4273 exception at the same time, we can embed the error token inside 4274 the exception so that the caller has a chance to retrieve it. 4275 This update adds a new GSSException constructor to include this 4276 token inside a GSSException object, and a getOutputToken() method 4277 to retrieve the token. The specification for the initSecContext 4278 and acceptSecContext methods are updated to describe the new 4279 behavior. Various examples are also updated. 4281 This is a compatible change. New JGSS programs should make use of 4282 this new feature but it is not mandatory. 4284 2) Removing stream-based GSSContext methods 4286 The overloaded methods of GSSContext that use input and output 4287 streams as the means to convey authentication and per-message GSS- 4288 API tokens as described in Section 5.15 of RFC 5653 [RFC5653] are 4289 removed in this update as the wire protocol should be defined by 4290 an application and not a library. It's also impossible to 4291 implement these methods correctly when the token has no self- 4292 framing (where the end cannot be determined) or the library has no 4293 knowledge of the token format (for example, as a bridge talking to 4294 another GSS library). These methods include initSecContext 4295 (Section 7.4.5 of RFC 5653 [RFC5653]), acceptSecContext 4296 (Section 7.4.9 of RFC 5653 [RFC5653]), wrap (Section 7.4.15 of RFC 4297 5653 [RFC5653]), unwrap (Section 7.4.17 of RFC 5653 [RFC5653]), 4298 getMIC (Section 7.4.19 of RFC 5653 [RFC5653]), and verifyMIC 4299 (Section 7.4.21 of RFC 5653 [RFC5653]). 4301 12. Changes since RFC 2853 4303 This document has following changes: 4305 1) Major GSS Status Code Constant Values 4307 RFC 2853 listed all the GSS status code values in two different 4308 sections: section 4.12.1 defined numeric values for them, and 4309 section 6.8.1 defined them as static constants in the GSSException 4310 class without assigning any values. Due to an inconsistent 4311 ordering between these two sections, all of the GSS major status 4312 codes resulted in misalignment, and a subsequent disagreement 4313 between deployed implementations. 4315 This document defines the numeric values of the GSS status codes 4316 in both sections, while maintaining the original ordering from 4317 section 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status 4318 code values defined in section 4.12.1. The relevant sections in 4319 this document are sections 4.12.1 and 6.8.1. 4321 2) GSS Credential Usage Constant Values 4323 RFC 2853 section 6.3.2 defines static constants for the 4324 GSSCredential usage flags. However, the values of these constants 4325 were not defined anywhere in RFC 2853 [RFC2853]. 4327 This document defines the credential usage values in section 4328 6.3.2. The original ordering of these values from section 6.3.2 4329 of RFC 2853 [RFC2853] is maintained. 4331 3) GSS Host-Based Service Name 4333 RFC 2853 [RFC2853], section 6.2.2, defines the static constant for 4334 the GSS host-based service OID NT_HOSTBASED_SERVICE, using a 4335 deprecated OID value. 4337 This document updates the NT_HOSTBASED_SERVICE OID value in 4338 section 6.2.2 to be consistent with the C-bindings in RFC 2744 4339 [RFC2744]. 4341 13. References 4343 13.1. Normative References 4345 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism 4346 (SPKM)", RFC 2025, DOI 10.17487/RFC2025, October 1996, 4347 . 4349 [RFC2743] Linn, J., "Generic Security Service Application Program 4350 Interface Version 2, Update 1", RFC 2743, 4351 DOI 10.17487/RFC2743, January 2000, 4352 . 4354 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 4355 C-bindings", RFC 2744, DOI 10.17487/RFC2744, January 2000, 4356 . 4358 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API 4359 Version 2 : Java Bindings", RFC 2853, 4360 DOI 10.17487/RFC2853, June 2000, 4361 . 4363 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 4364 Version 5 Generic Security Service Application Program 4365 Interface (GSS-API) Mechanism: Version 2", RFC 4121, 4366 DOI 10.17487/RFC4121, July 2005, 4367 . 4369 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The 4370 Simple and Protected Generic Security Service Application 4371 Program Interface (GSS-API) Negotiation Mechanism", 4372 RFC 4178, DOI 10.17487/RFC4178, October 2005, 4373 . 4375 [RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API 4376 Version 2: Java Bindings Update", RFC 5653, 4377 DOI 10.17487/RFC5653, August 2009, 4378 . 4380 13.2. Informative References 4382 [JLS] Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java 4383 Language Specification", Third Edition, 2005, 4384 . 4386 Authors' Addresses 4388 Mayank D. Upadhyay 4389 Google Inc. 4390 1600 Amphitheatre Parkway 4391 Mountain View, CA 94043 4392 USA 4394 Email: m.d.upadhyay+ietf@gmail.com 4396 Seema Malkani 4397 ActivIdentity Corp. 4398 6623 Dumbarton Circle 4399 Fremont, California 94555 4400 USA 4402 Email: Seema.Malkani@gmail.com 4403 Wang Weijun 4404 Oracle 4405 Building No. 24, Zhongguancun Software Park 4406 Beijing 100193 4407 China 4409 Email: weijun.wang@oracle.com