idnits 2.17.1 draft-ietf-kitten-rfc5653bis-00.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 date (May 23, 2014) is 3597 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) == Missing Reference: 'RFC2853' is mentioned on line 4562, but not defined ** Obsolete undefined 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: November 24, 2014 W. Wang 7 Oracle 8 May 23, 2014 10 Generic Security Service API Version 2: Java Bindings Update 11 draft-ietf-kitten-rfc5653bis-00 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. 26 The GSS-API is described at a language-independent conceptual level 27 in "Generic Security Service Application Program Interface Version 2, 28 Update 1" (RFC 2743). The GSS-API allows a caller application to 29 authenticate a principal identity, to delegate rights to a peer, and 30 to apply security services such as confidentiality and integrity on a 31 per-message basis. Examples of security mechanisms defined for GSS- 32 API are "The Simple Public-Key GSS-API Mechanism" (RFC 2025) and "The 33 Kerberos Version 5 Generic Security Service Application Program 34 Interface (GSS-API) Mechanism: Version 2" (RFC 4121). 36 Status of This Memo 38 This Internet-Draft is submitted in full conformance with the 39 provisions of BCP 78 and BCP 79. 41 Internet-Drafts are working documents of the Internet Engineering 42 Task Force (IETF). Note that other groups may also distribute 43 working documents as Internet-Drafts. The list of current Internet- 44 Drafts is at http://datatracker.ietf.org/drafts/current/. 46 Internet-Drafts are draft documents valid for a maximum of six months 47 and may be updated, replaced, or obsoleted by other documents at any 48 time. It is inappropriate to use Internet-Drafts as reference 49 material or to cite them other than as "work in progress." 51 This Internet-Draft will expire on November 24, 2014. 53 Copyright Notice 55 Copyright (c) 2014 IETF Trust and the persons identified as the 56 document authors. All rights reserved. 58 This document is subject to BCP 78 and the IETF Trust's Legal 59 Provisions Relating to IETF Documents 60 (http://trustee.ietf.org/license-info) in effect on the date of 61 publication of this document. Please review these documents 62 carefully, as they describe your rights and restrictions with respect 63 to this document. Code Components extracted from this document must 64 include Simplified BSD License text as described in Section 4.e of 65 the Trust Legal Provisions and are provided without warranty as 66 described in the Simplified BSD License. 68 Table of Contents 70 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 71 2. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 7 72 3. Additional Controls . . . . . . . . . . . . . . . . . . . . . 8 73 3.1. Delegation . . . . . . . . . . . . . . . . . . . . . . . 9 74 3.2. Mutual Authentication . . . . . . . . . . . . . . . . . . 10 75 3.3. Replay and Out-of-Sequence Detection . . . . . . . . . . 11 76 3.4. Anonymous Authentication . . . . . . . . . . . . . . . . 11 77 3.5. Confidentiality . . . . . . . . . . . . . . . . . . . . . 12 78 3.6. Inter-process Context Transfer . . . . . . . . . . . . . 13 79 3.7. The Use of Incomplete Contexts . . . . . . . . . . . . . 13 80 4. Calling Conventions . . . . . . . . . . . . . . . . . . . . . 14 81 4.1. Package Name . . . . . . . . . . . . . . . . . . . . . . 14 82 4.2. Provider Framework . . . . . . . . . . . . . . . . . . . 14 83 4.3. Integer Types . . . . . . . . . . . . . . . . . . . . . . 15 84 4.4. Opaque Data Types . . . . . . . . . . . . . . . . . . . . 15 85 4.5. Strings . . . . . . . . . . . . . . . . . . . . . . . . . 15 86 4.6. Object Identifiers . . . . . . . . . . . . . . . . . . . 16 87 4.7. Object Identifier Sets . . . . . . . . . . . . . . . . . 16 88 4.8. Credentials . . . . . . . . . . . . . . . . . . . . . . . 16 89 4.9. Contexts . . . . . . . . . . . . . . . . . . . . . . . . 18 90 4.10. Authentication Tokens . . . . . . . . . . . . . . . . . . 19 91 4.11. Inter-Process Tokens . . . . . . . . . . . . . . . . . . 19 92 4.12. Error Reporting . . . . . . . . . . . . . . . . . . . . . 19 93 4.12.1. GSS Status Codes . . . . . . . . . . . . . . . . . . 20 94 4.12.2. Mechanism-Specific Status Codes . . . . . . . . . . 22 95 4.12.3. Supplementary Status Codes . . . . . . . . . . . . . 22 96 4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 23 97 4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . . 26 98 4.15. Stream Objects . . . . . . . . . . . . . . . . . . . . . 27 99 4.16. Optional Parameters . . . . . . . . . . . . . . . . . . . 28 100 5. Introduction to GSS-API Classes and Interfaces . . . . . . . 28 101 5.1. GSSManager Class . . . . . . . . . . . . . . . . . . . . 28 102 5.2. GSSName Interface . . . . . . . . . . . . . . . . . . . . 29 103 5.3. GSSCredential Interface . . . . . . . . . . . . . . . . . 30 104 5.4. GSSContext Interface . . . . . . . . . . . . . . . . . . 31 105 5.5. MessageProp Class . . . . . . . . . . . . . . . . . . . . 32 106 5.6. GSSException Class . . . . . . . . . . . . . . . . . . . 32 107 5.7. Oid Class . . . . . . . . . . . . . . . . . . . . . . . . 33 108 5.8. ChannelBinding Class . . . . . . . . . . . . . . . . . . 33 109 6. Detailed GSS-API Class Description . . . . . . . . . . . . . 33 110 6.1. public abstract class GSSManager . . . . . . . . . . . . 33 111 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . 35 112 6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 35 113 6.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . 35 114 6.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 35 115 6.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 36 116 6.1.6. createName . . . . . . . . . . . . . . . . . . . . . 36 117 6.1.7. createName . . . . . . . . . . . . . . . . . . . . . 36 118 6.1.8. createName . . . . . . . . . . . . . . . . . . . . . 37 119 6.1.9. createName . . . . . . . . . . . . . . . . . . . . . 37 120 6.1.10. createCredential . . . . . . . . . . . . . . . . . . 38 121 6.1.11. createCredential . . . . . . . . . . . . . . . . . . 38 122 6.1.12. createCredential . . . . . . . . . . . . . . . . . . 39 123 6.1.13. createContext . . . . . . . . . . . . . . . . . . . . 40 124 6.1.14. createContext . . . . . . . . . . . . . . . . . . . . 40 125 6.1.15. createContext . . . . . . . . . . . . . . . . . . . . 40 126 6.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . 41 127 6.1.17. Example Code . . . . . . . . . . . . . . . . . . . . 41 128 6.1.18. addProviderAtEnd . . . . . . . . . . . . . . . . . . 42 129 6.1.19. Example Code . . . . . . . . . . . . . . . . . . . . 43 130 6.2. public interface GSSName . . . . . . . . . . . . . . . . 44 131 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . 44 132 6.2.2. Static Constants . . . . . . . . . . . . . . . . . . 45 133 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . 46 134 6.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . 46 135 6.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . 46 136 6.2.6. export . . . . . . . . . . . . . . . . . . . . . . . 47 137 6.2.7. toString . . . . . . . . . . . . . . . . . . . . . . 47 138 6.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 47 139 6.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 47 140 6.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . 47 141 6.3. public interface GSSCredential implements Cloneable . . . 48 142 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . 49 143 6.3.2. Static Constants . . . . . . . . . . . . . . . . . . 49 144 6.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 50 145 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 50 146 6.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 50 147 6.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . 50 148 6.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . 50 149 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . 51 150 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 51 151 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 51 152 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 52 153 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 52 154 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 53 155 6.4. public interface GSSContext . . . . . . . . . . . . . . . 53 156 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 54 157 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . 56 158 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . 56 159 6.4.4. Example Code . . . . . . . . . . . . . . . . . . . . 57 160 6.4.5. initSecContext . . . . . . . . . . . . . . . . . . . 58 161 6.4.6. Example Code . . . . . . . . . . . . . . . . . . . . 58 162 6.4.7. acceptSecContext . . . . . . . . . . . . . . . . . . 59 163 6.4.8. Example Code . . . . . . . . . . . . . . . . . . . . 60 164 6.4.9. acceptSecContext . . . . . . . . . . . . . . . . . . 61 165 6.4.10. Example Code . . . . . . . . . . . . . . . . . . . . 62 166 6.4.11. isEstablished . . . . . . . . . . . . . . . . . . . . 63 167 6.4.12. dispose . . . . . . . . . . . . . . . . . . . . . . . 63 168 6.4.13. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 63 169 6.4.14. wrap . . . . . . . . . . . . . . . . . . . . . . . . 64 170 6.4.15. wrap . . . . . . . . . . . . . . . . . . . . . . . . 65 171 6.4.16. unwrap . . . . . . . . . . . . . . . . . . . . . . . 66 172 6.4.17. unwrap . . . . . . . . . . . . . . . . . . . . . . . 67 173 6.4.18. getMIC . . . . . . . . . . . . . . . . . . . . . . . 67 174 6.4.19. getMIC . . . . . . . . . . . . . . . . . . . . . . . 68 175 6.4.20. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 69 176 6.4.21. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 70 177 6.4.22. export . . . . . . . . . . . . . . . . . . . . . . . 70 178 6.4.23. requestMutualAuth . . . . . . . . . . . . . . . . . . 71 179 6.4.24. requestReplayDet . . . . . . . . . . . . . . . . . . 71 180 6.4.25. requestSequenceDet . . . . . . . . . . . . . . . . . 71 181 6.4.26. requestCredDeleg . . . . . . . . . . . . . . . . . . 72 182 6.4.27. requestAnonymity . . . . . . . . . . . . . . . . . . 72 183 6.4.28. requestConf . . . . . . . . . . . . . . . . . . . . . 72 184 6.4.29. requestInteg . . . . . . . . . . . . . . . . . . . . 72 185 6.4.30. requestLifetime . . . . . . . . . . . . . . . . . . . 72 186 6.4.31. setChannelBinding . . . . . . . . . . . . . . . . . . 73 187 6.4.32. getCredDelegState . . . . . . . . . . . . . . . . . . 73 188 6.4.33. getMutualAuthState . . . . . . . . . . . . . . . . . 73 189 6.4.34. getReplayDetState . . . . . . . . . . . . . . . . . . 73 190 6.4.35. getSequenceDetState . . . . . . . . . . . . . . . . . 74 191 6.4.36. getAnonymityState . . . . . . . . . . . . . . . . . . 74 192 6.4.37. isTransferable . . . . . . . . . . . . . . . . . . . 74 193 6.4.38. isProtReady . . . . . . . . . . . . . . . . . . . . . 74 194 6.4.39. getConfState . . . . . . . . . . . . . . . . . . . . 74 195 6.4.40. getIntegState . . . . . . . . . . . . . . . . . . . . 74 196 6.4.41. getLifetime . . . . . . . . . . . . . . . . . . . . . 75 197 6.4.42. getSrcName . . . . . . . . . . . . . . . . . . . . . 75 198 6.4.43. getTargName . . . . . . . . . . . . . . . . . . . . . 75 199 6.4.44. getMech . . . . . . . . . . . . . . . . . . . . . . . 75 200 6.4.45. getDelegCred . . . . . . . . . . . . . . . . . . . . 75 201 6.4.46. isInitiator . . . . . . . . . . . . . . . . . . . . . 76 202 6.5. public class MessageProp . . . . . . . . . . . . . . . . 76 203 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 76 204 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 76 205 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 77 206 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 77 207 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 77 208 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 77 209 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 77 210 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 77 211 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 78 212 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 78 213 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 78 214 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 78 215 6.6. public class ChannelBinding . . . . . . . . . . . . . . . 79 216 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 79 217 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 80 218 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 80 219 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . 80 220 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 80 221 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 80 222 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 81 223 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 81 224 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 81 225 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 81 226 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 82 227 6.8. public class GSSException extends Exception . . . . . . . 82 228 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . 82 229 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 85 230 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 86 231 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 86 232 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 86 233 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 86 234 6.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 86 235 6.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 87 236 6.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 87 237 6.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 87 239 7. Sample Applications . . . . . . . . . . . . . . . . . . . . . 87 240 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 87 241 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 91 242 8. Security Considerations . . . . . . . . . . . . . . . . . . . 95 243 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 96 244 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 96 245 11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 96 246 12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 97 247 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 98 248 13.1. Normative References . . . . . . . . . . . . . . . . . . 98 249 13.2. Informative References . . . . . . . . . . . . . . . . . 98 250 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 98 252 1. Introduction 254 This document specifies Java language bindings for the Generic 255 Security Services Application Programming Interface version 2 (GSS- 256 API). GSS-API version 2 is described in a language-independent 257 format in RFC 2743 [RFC2743]. The GSS-API allows a caller 258 application to authenticate a principal identity, to delegate rights 259 to a peer, and to apply security services such as confidentiality and 260 integrity on a per-message basis. 262 This document and its predecessor, RFC 5653 [RFC5653], leverage the 263 work done by the working group (WG) in the area of RFC 2743 [RFC2743] 264 and the C-bindings of RFC 2744 [RFC2744]. Whenever appropriate, text 265 has been used from the C-bindings document (RFC 2744) to explain 266 generic concepts and provide direction to the implementors. 268 The design goals of this API have been to satisfy all the 269 functionality defined in RFC 2743 [RFC2743] and to provide these 270 services in an object-oriented method. The specification also aims 271 to satisfy the needs of both types of Java application developers, 272 those who would like access to a "system-wide" GSS-API 273 implementation, as well as those who would want to provide their own 274 "custom" implementation. 276 A system-wide implementation is one that is available to all 277 applications in the form of a library package. It may be the 278 standard package in the Java runtime environment (JRE) being used or 279 it may be additionally installed and accessible to any application 280 via the CLASSPATH. 282 A custom implementation of the GSS-API, on the other hand, is one 283 that would, in most cases, be bundled with the application during 284 distribution. It is expected that such an implementation would be 285 meant to provide for some particular need of the application, such as 286 support for some specific mechanism. 288 The design of this API also aims to provide a flexible framework to 289 add and manage GSS-API mechanisms. GSS-API leverages the Java 290 Cryptography Architecture (JCA) provider model to support the 291 plugability of mechanisms. Mechanisms can be added on a system-wide 292 basis, where all users of the framework will have them available. 293 The specification also allows for the addition of mechanisms per- 294 instance of the GSS-API. 296 Lastly, this specification presents an API that will naturally fit 297 within the operation environment of the Java platform. Readers are 298 assumed to be familiar with both the GSS-API and the Java platform. 300 2. GSS-API Operational Paradigm 302 "Generic Security Service Application Programming Interface, Version 303 2" [RFC2743] defines a generic security API to calling applications. 304 It allows a communicating application to authenticate the user 305 associated with another application, to delegate rights to another 306 application, and to apply security services such as confidentiality 307 and integrity on a per-message basis. 309 There are four stages to using GSS-API: 311 1) The application acquires a set of credentials with which it may 312 prove its identity to other processes. The application's 313 credentials vouch for its global identity, which may or may not be 314 related to any local username under which it may be running. 316 2) A pair of communicating applications establish a joint security 317 context using their credentials. The security context 318 encapsulates shared state information, which is required in order 319 that per-message security services may be provided. Examples of 320 state information that might be shared between applications as 321 part of a security context are cryptographic keys and message 322 sequence numbers. As part of the establishment of a security 323 context, the context initiator is authenticated to the responder, 324 and may require that the responder is authenticated back to the 325 initiator. The initiator may optionally give the responder the 326 right to initiate further security contexts, acting as an agent or 327 delegate of the initiator. This transfer of rights is termed 328 "delegation", and is achieved by creating a set of credentials, 329 similar to those used by the initiating application, but which may 330 be used by the responder. 332 A GSSContext object is used to establish and maintain the shared 333 information that makes up the security context. Certain 334 GSSContext methods will generate a token, which applications treat 335 as cryptographically protected, opaque data. The caller of such a 336 GSSContext method is responsible for transferring the token to the 337 peer application, encapsulated if necessary in an application-to- 338 application protocol. On receipt of such a token, the peer 339 application should pass it to a corresponding GSSContext method 340 which will decode the token and extract the information, updating 341 the security context state information accordingly. 343 3) Per-message services are invoked on a GSSContext object to apply 344 either: 346 integrity and data origin authentication, or 348 confidentiality, integrity and data origin authentication 350 to application data, which are treated by GSS-API as arbitrary 351 octet-strings. An application transmitting a message that it 352 wishes to protect will call the appropriate GSSContext method 353 (getMIC or wrap) to apply protection, and send the resulting token 354 to the receiving application. The receiver will pass the received 355 token (and, in the case of data protected by getMIC, the 356 accompanying message-data) to the corresponding decoding method of 357 the GSSContext interface (verifyMIC or unwrap) to remove the 358 protection and validate the data. 360 4) At the completion of a communications session (which may extend 361 across several transport connections), each application uses a 362 GSSContext method to invalidate the security context and release 363 any system or cryptographic resources held. Multiple contexts may 364 also be used (either successively or simultaneously) within a 365 single communications association, at the discretion of the 366 applications. 368 3. Additional Controls 370 This section discusses the optional services that a context initiator 371 may request of the GSS-API before the context establishment. Each of 372 these services is requested by calling the appropriate mutator method 373 in the GSSContext object before the first call to init is performed. 374 Only the context initiator can request context flags. 376 The optional services defined are: 378 Delegation: The (usually temporary) transfer of rights from 379 initiator to acceptor, enabling the acceptor to authenticate 380 itself as an agent of the initiator. 382 Mutual Authentication: In addition to the initiator authenticating 383 its identity to the context acceptor, the context acceptor should 384 also authenticate itself to the initiator. 386 Replay Detection: In addition to providing message integrity 387 services, GSSContext per-message operations of getMIC and wrap 388 should include message numbering information to enable verifyMIC 389 and unwrap to detect if a message has been duplicated. 391 Out-of-Sequence Detection: In addition to providing message 392 integrity services, GSSContext per-message operations (getMIC and 393 wrap) should include message sequencing information to enable 394 verifyMIC and unwrap to detect if a message has been received out 395 of sequence. 397 Anonymous Authentication: The establishment of the security 398 context should not reveal the initiator's identity to the context 399 acceptor. 401 Some mechanisms may not support all optional services, and some 402 mechanisms may only support some services in conjunction with others. 403 The GSSContext interface offers query methods to allow the 404 verification by the calling application of which services will be 405 available from the context when the establishment phase is complete. 406 In general, if the security mechanism is capable of providing a 407 requested service, it should do so even if additional services must 408 be enabled in order to provide the requested service. If the 409 mechanism is incapable of providing a requested service, it should 410 proceed without the service leaving the application to abort the 411 context establishment process if it considers the requested service 412 to be mandatory. 414 Some mechanisms may specify that support for some services is 415 optional, and that implementors of the mechanism need not provide it. 416 This is most commonly true of the confidentiality service, often 417 because of legal restrictions on the use of data-encryption, but may 418 apply to any of the services. Such mechanisms are required to send 419 at least one token from acceptor to initiator during context 420 establishment when the initiator indicates a desire to use such a 421 service, so that the initiating GSS-API can correctly indicate 422 whether the service is supported by the acceptor's GSS-API. 424 3.1. Delegation 425 The GSS-API allows delegation to be controlled by the initiating 426 application via the requestCredDeleg method before the first call to 427 init has been issued. Some mechanisms do not support delegation, and 428 for such mechanisms, attempts by an application to enable delegation 429 are ignored. 431 The acceptor of a security context, for which the initiator enabled 432 delegation, can check if delegation was enabled by using the 433 getCredDelegState method of the GSSContext interface. In cases when 434 it is enabled, the delegated credential object can be obtained by 435 calling the getDelegCred method. The obtained GSSCredential object 436 may then be used to initiate subsequent GSS-API security contexts as 437 an agent or delegate of the initiator. If the original initiator's 438 identity is "A" and the delegate's identity is "B", then, depending 439 on the underlying mechanism, the identity embodied by the delegated 440 credential may be either "A" or "B acting for A". 442 For many mechanisms that support delegation, a simple boolean does 443 not provide enough control. Examples of additional aspects of 444 delegation control that a mechanism might provide to an application 445 are duration of delegation, network addresses from which delegation 446 is valid, and constraints on the tasks that may be performed by a 447 delegate. Such controls are presently outside the scope of the GSS- 448 API. GSS-API implementations supporting mechanisms offering 449 additional controls should provide extension routines that allow 450 these controls to be exercised (perhaps by modifying the initiator's 451 GSS-API credential object prior to its use in establishing a 452 context). However, the simple delegation control provided by GSS-API 453 should always be able to override other mechanism-specific delegation 454 controls. If the application instructs the GSSContext object that 455 delegation is not desired, then the implementation must not permit 456 delegation to occur. This is an exception to the general rule that a 457 mechanism may enable services even if they are not requested -- 458 delegation may only be provided at the explicit request of the 459 application. 461 3.2. Mutual Authentication 463 Usually, a context acceptor will require that a context initiator 464 authenticate itself so that the acceptor may make an access-control 465 decision prior to performing a service for the initiator. In some 466 cases, the initiator may also request that the acceptor authenticate 467 itself. GSS-API allows the initiating application to request this 468 mutual authentication service by calling the requestMutualAuth method 469 of the GSSContext interface with a "true" parameter before making the 470 first call to init. The initiating application is informed as to 471 whether or not the context acceptor has authenticated itself. Note 472 that some mechanisms may not support mutual authentication, and other 473 mechanisms may always perform mutual authentication, whether or not 474 the initiating application requests it. In particular, mutual 475 authentication may be required by some mechanisms in order to support 476 replay or out-of-sequence message detection, and for such mechanisms, 477 a request for either of these services will automatically enable 478 mutual authentication. 480 3.3. Replay and Out-of-Sequence Detection 482 The GSS-API may provide detection of mis-ordered messages once a 483 security context has been established. Protection may be applied to 484 messages by either application, by calling either getMIC or wrap 485 methods of the GSSContext interface, and verified by the peer 486 application by calling verifyMIC or unwrap for the peer's GSSContext 487 object. 489 The getMIC method calculates a cryptographic checksum of an 490 application message, and returns that checksum in a token. The 491 application should pass both the token and the message to the peer 492 application, which presents them to the verifyMIC method of the 493 peer's GSSContext object. 495 The wrap method calculates a cryptographic checksum of an application 496 message, and places both the checksum and the message inside a single 497 token. The application should pass the token to the peer 498 application, which presents it to the unwrap method of the peer's 499 GSSContext object to extract the message and verify the checksum. 501 Either pair of routines may be capable of detecting out-of-sequence 502 message delivery or the duplication of messages. Details of such 503 mis-ordered messages are indicated through supplementary query 504 methods of the MessageProp object that is filled in by each of these 505 routines. 507 A mechanism need not maintain a list of all tokens that have been 508 processed in order to support these status codes. A typical 509 mechanism might retain information about only the most recent "N" 510 tokens processed, allowing it to distinguish duplicates and missing 511 tokens within the most recent "N" messages; the receipt of a token 512 older than the most recent "N" would result in the isOldToken method 513 of the instance of MessageProp to return "true". 515 3.4. Anonymous Authentication 517 In certain situations, an application may wish to initiate the 518 authentication process to authenticate a peer, without revealing its 519 own identity. As an example, consider an application providing 520 access to a database containing medical information and offering 521 unrestricted access to the service. A client of such a service might 522 wish to authenticate the service (in order to establish trust in any 523 information retrieved from it), but might not wish the service to be 524 able to obtain the client's identity (perhaps due to privacy concerns 525 about the specific inquiries, or perhaps simply to avoid being placed 526 on mailing-lists). 528 In normal use of the GSS-API, the initiator's identity is made 529 available to the acceptor as a result of the context establishment 530 process. However, context initiators may request that their identity 531 not be revealed to the context acceptor. Many mechanisms do not 532 support anonymous authentication, and for such mechanisms, the 533 request will not be honored. An authentication token will still be 534 generated, but the application is always informed if a requested 535 service is unavailable, and has the option to abort context 536 establishment if anonymity is valued above the other security 537 services that would require a context to be established. 539 In addition to informing the application that a context is 540 established anonymously (via the isAnonymous method of the GSSContext 541 class), the getSrcName method of the acceptor's GSSContext object 542 will, for such contexts, return a reserved internal-form name, 543 defined by the implementation. 545 The toString method for a GSSName object representing an anonymous 546 entity will return a printable name. The returned value will be 547 syntactically distinguishable from any valid principal name supported 548 by the implementation. The associated name-type object identifier 549 will be an oid representing the value of NT_ANONYMOUS. This name- 550 type oid will be defined as a public, static Oid object of the 551 GSSName class. The printable form of an anonymous name should be 552 chosen such that it implies anonymity, since this name may appear in, 553 for example, audit logs. For example, the string "" might 554 be a good choice, if no valid printable names supported by the 555 implementation can begin with "<" and end with ">". 557 When using the equal method of the GSSName interface, and one of the 558 operands is a GSSName instance representing an anonymous entity, the 559 method must return "false". 561 3.5. Confidentiality 563 If a GSSContext supports the confidentiality service, wrap method may 564 be used to encrypt application messages. Messages are selectively 565 encrypted, under the control of the setPrivacy method of the 566 MessageProp object used in the wrap method. 568 3.6. Inter-process Context Transfer 570 GSS-APIv2 provides functionality that allows a security context to be 571 transferred between processes on a single machine. These are 572 implemented using the export method of GSSContext and a byte array 573 constructor of the same class. The most common use for such a 574 feature is a client-server design where the server is implemented as 575 a single process that accepts incoming security contexts, which then 576 launches child processes to deal with the data on these contexts. In 577 such a design, the child processes must have access to the security 578 context object created within the parent so that they can use per- 579 message protection services and delete the security context when the 580 communication session ends. 582 Since the security context data structure is expected to contain 583 sequencing information, it is impractical in general to share a 584 context between processes. Thus, the GSSContext interface provides 585 an export method that the process, which currently owns the context, 586 can call to declare that it has no intention to use the context 587 subsequently, and to create an inter-process token containing 588 information needed by the adopting process to successfully recreate 589 the context. After successful completion of export, the original 590 security context is made inaccessible to the calling process by GSS- 591 API, and any further usage of this object will result in failures. 592 The originating process transfers the inter-process token to the 593 adopting process, which creates a new GSSContext object using the 594 byte array constructor. The properties of the context are equivalent 595 to that of the original context. 597 The inter-process token may contain sensitive data from the original 598 security context (including cryptographic keys). Applications using 599 inter-process tokens to transfer security contexts must take 600 appropriate steps to protect these tokens in transit. 602 Implementations are not required to support the inter-process 603 transfer of security contexts. Calling the isTransferable method of 604 the GSSContext interface will indicate if the context object is 605 transferable. 607 3.7. The Use of Incomplete Contexts 608 Some mechanisms may allow the per-message services to be used before 609 the context establishment process is complete. For example, a 610 mechanism may include sufficient information in its initial context- 611 level tokens for the context acceptor to immediately decode messages 612 protected with wrap or getMIC. For such a mechanism, the initiating 613 application need not wait until subsequent context-level tokens have 614 been sent and received before invoking the per-message protection 615 services. 617 An application can invoke the isProtReady method of the GSSContext 618 class to determine if the per-message services are available in 619 advance of complete context establishment. Applications wishing to 620 use per-message protection services on partially established contexts 621 should query this method before attempting to invoke wrap or getMIC. 623 4. Calling Conventions 625 Java provides the implementors with not just a syntax for the 626 language, but also an operational environment. For example, memory 627 is automatically managed and does not require application 628 intervention. These language features have allowed for a simpler API 629 and have led to the elimination of certain GSS-API functions. 631 Moreover, the JCA defines a provider model that allows for 632 implementation-independent access to security services. Using this 633 model, applications can seamlessly switch between different 634 implementations and dynamically add new services. The GSS-API 635 specification leverages these concepts by the usage of providers for 636 the mechanism implementations. 638 4.1. Package Name 640 The classes and interfaces defined in this document reside in the 641 package called "org.ietf.jgss". Applications that wish to make use 642 of this API should import this package name as shown in section 7. 644 4.2. Provider Framework 646 The Java security API's use a provider architecture that allows 647 applications to be implementation independent and security API 648 implementations to be modular and extensible. The 649 java.security.Provider class is an abstract class that a vendor 650 extends. This class maps various properties that represent different 651 security services that are available to the names of the actual 652 vendor classes that implement those services. When requesting a 653 service, an application simply specifies the desired provider and the 654 API delegates the request to service classes available from that 655 provider. 657 Using the Java security provider model insulates applications from 658 implementation details of the services they wish to use. 659 Applications can switch between providers easily and new providers 660 can be added as needed, even at runtime. 662 The GSS-API may use providers to find components for specific 663 underlying security mechanisms. For instance, a particular provider 664 might contain components that will allow the GSS-API to support the 665 Kerberos v5 mechanism [RFC4121] and another might contain components 666 to support the Simple Public-Key GSS-API Mechanism (SPKM) [RFC2025]. 667 By delegating mechanism-specific functionality to the components 668 obtained from providers, the GSS-API can be extended to support an 669 arbitrary list of mechanism. 671 How the GSS-API locates and queries these providers is beyond the 672 scope of this document and is being deferred to a Service Provider 673 Interface (SPI) specification. The availability of such an SPI 674 specification is not mandatory for the adoption of this API 675 specification nor is it mandatory to use providers in the 676 implementation of a GSS-API framework. However, by using the 677 provider framework together with an SPI specification, one can create 678 an extensible and implementation-independent GSS-API framework. 680 4.3. Integer Types 682 All numeric values are declared as "int" primitive Java type. The 683 Java specification guarantees that this will be a 32-bit two's 684 complement signed number. 686 Throughout this API, the "boolean" primitive Java type is used 687 wherever a boolean value is required or returned. 689 4.4. Opaque Data Types 691 Java byte arrays are used to represent opaque data types that are 692 consumed and produced by the GSS-API in the form of tokens. Java 693 arrays contain a length field that enables the users to easily 694 determine their size. The language has automatic garbage collection 695 that alleviates the need by developers to release memory and 696 simplifies buffer ownership issues. 698 4.5. Strings 700 The String object will be used to represent all textual data. The 701 Java String object transparently treats all characters as two-byte 702 Unicode characters, which allows support for many locals. All 703 routines returning or accepting textual data will use the String 704 object. 706 4.6. Object Identifiers 708 An Oid object will be used to represent Universal Object Identifiers 709 (Oids). Oids are ISO-defined, hierarchically globally interpretable 710 identifiers used within the GSS-API framework to identify security 711 mechanisms and name formats. The Oid object can be created from a 712 string representation of its dot notation (e.g., "1.3.6.1.5.6.2") as 713 well as from its ASN.1 DER encoding. Methods are also provided to 714 test equality and provide the DER representation for the object. 716 An important feature of the Oid class is that its instances are 717 immutable -- i.e., there are no methods defined that allow one to 718 change the contents of an Oid. This property allows one to treat 719 these objects as "statics" without the need to perform copies. 721 Certain routines allow the usage of a default oid. A "null" value 722 can be used in those cases. 724 4.7. Object Identifier Sets 726 The Java bindings represent object identifier sets as arrays of Oid 727 objects. All Java arrays contain a length field, which allows for 728 easy manipulation and reference. 730 In order to support the full functionality of RFC 2743 [RFC2743], the 731 Oid class includes a method that checks for existence of an Oid 732 object within a specified array. This is equivalent in functionality 733 to gss_test_oid_set_member. The use of Java arrays and Java's 734 automatic garbage collection has eliminated the need for the 735 following routines: gss_create_empty_oid_set, gss_release_oid_set, 736 and gss_add_oid_set_member. Java GSS-API implementations will not 737 contain them. Java's automatic garbage collection and the immutable 738 property of the Oid object eliminates the memory management issues of 739 the C counterpart. 741 Whenever a default value for an Object Identifier Set is required, a 742 "null" value can be used. Please consult the detailed method 743 description for details. 745 4.8. Credentials 747 GSS-API credentials are represented by the GSSCredential interface. 748 The interface contains several constructs to allow for the creation 749 of most common credential objects for the initiator and the acceptor. 750 Comparisons are performed using the interface's "equals" method. The 751 following general description of GSS-API credentials is included from 752 the C-bindings specification: 754 GSS-API credentials can contain mechanism-specific principal 755 authentication data for multiple mechanisms. A GSS-API credential 756 is composed of a set of credential-elements, each of which is 757 applicable to a single mechanism. A credential may contain at 758 most one credential-element for each supported mechanism. A 759 credential-element identifies the data needed by a single 760 mechanism to authenticate a single principal, and conceptually 761 contains two credential-references that describe the actual 762 mechanism-specific authentication data, one to be used by GSS-API 763 for initiating contexts, and one to be used for accepting 764 contexts. For mechanisms that do not distinguish between acceptor 765 and initiator credentials, both references would point to the same 766 underlying mechanism-specific authentication data. 768 Credentials describe a set of mechanism-specific principals, and give 769 their holder the ability to act as any of those principals. All 770 principal identities asserted by a single GSS-API credential should 771 belong to the same entity, although enforcement of this property is 772 an implementation-specific matter. A single GSSCredential object 773 represents all the credential elements that have been acquired. 775 The creation of an GSSContext object allows the value of "null" to be 776 specified as the GSSCredential input parameter. This will indicate a 777 desire by the application to act as a default principal. While 778 individual GSS-API implementations are free to determine such default 779 behavior as appropriate to the mechanism, the following default 780 behavior by these routines is recommended for portability: 782 For the initiator side of the context: 784 1) If there is only a single principal capable of initiating security 785 contexts for the chosen mechanism that the application is 786 authorized to act on behalf of, then that principal shall be used; 787 otherwise, 789 2) If the platform maintains a concept of a default network-identity 790 for the chosen mechanism, and if the application is authorized to 791 act on behalf of that identity for the purpose of initiating 792 security contexts, then the principal corresponding to that 793 identity shall be used; otherwise, 795 3) If the platform maintains a concept of a default local identity, 796 and provides a means to map local identities into network- 797 identities for the chosen mechanism, and if the application is 798 authorized to act on behalf of the network-identity image of the 799 default local identity for the purpose of initiating security 800 contexts using the chosen mechanism, then the principal 801 corresponding to that identity shall be used; otherwise, 803 4) A user-configurable default identity should be used. 805 For the acceptor side of the context: 807 1) If there is only a single authorized principal identity capable of 808 accepting security contexts for the chosen mechanism, then that 809 principal shall be used; otherwise, 811 2) If the mechanism can determine the identity of the target 812 principal by examining the context-establishment token processed 813 during the accept method, and if the accepting application is 814 authorized to act as that principal for the purpose of accepting 815 security contexts using the chosen mechanism, then that principal 816 identity shall be used; otherwise, 818 3) If the mechanism supports context acceptance by any principal, and 819 if mutual authentication was not requested, any principal that the 820 application is authorized to accept security contexts under using 821 the chosen mechanism may be used; otherwise, 823 4) A user-configurable default identity shall be used. 825 The purpose of the above rules is to allow security contexts to be 826 established by both initiator and acceptor using the default behavior 827 whenever possible. Applications requesting default behavior are 828 likely to be more portable across mechanisms and implementations than 829 ones that instantiate an GSSCredential object representing a specific 830 identity. 832 4.9. Contexts 834 The GSSContext interface is used to represent one end of a GSS-API 835 security context, storing state information appropriate to that end 836 of the peer communication, including cryptographic state information. 837 The instantiation of the context object is done differently by the 838 initiator and the acceptor. After the context has been instantiated, 839 the initiator may choose to set various context options that will 840 determine the characteristics of the desired security context. When 841 all the application-desired characteristics have been set, the 842 initiator will call the initSecContext method, which will produce a 843 token for consumption by the peer's acceptSecContext method. It is 844 the responsibility of the application to deliver the authentication 845 token(s) between the peer applications for processing. Upon 846 completion of the context-establishment phase, context attributes can 847 be retrieved, by both the initiator and acceptor, using the accessor 848 methods. These will reflect the actual attributes of the established 849 context. At this point, the context can be used by the application 850 to apply cryptographic services to its data. 852 4.10. Authentication Tokens 854 A token is a caller-opaque type that GSS-API uses to maintain 855 synchronization between each end of the GSS-API security context. 856 The token is a cryptographically protected octet-string, generated by 857 the underlying mechanism at one end of a GSS-API security context for 858 use by the peer mechanism at the other end. Encapsulation (if 859 required) within the application protocol and transfer of the token 860 are the responsibility of the peer applications. 862 Java GSS-API uses byte arrays to represent authentication tokens. 863 Overloaded methods exist that allow the caller to supply input and 864 output streams that will be used for the reading and writing of the 865 token data. 867 4.11. Inter-Process Tokens 869 Certain GSS-API routines are intended to transfer data between 870 processes in multi-process programs. These routines use a caller- 871 opaque octet-string, generated by the GSS-API in one process for use 872 by the GSS-API in another process. The calling application is 873 responsible for transferring such tokens between processes. Note 874 that, while GSS-API implementors are encouraged to avoid placing 875 sensitive information within inter-process tokens, or to 876 cryptographically protect them, many implementations will be unable 877 to avoid placing key material or other sensitive data within them. 878 It is the application's responsibility to ensure that inter-process 879 tokens are protected in transit, and transferred only to processes 880 that are trustworthy. An inter-process token is represented using a 881 byte array emitted from the export method of the GSSContext 882 interface. The receiver of the inter-process token would initialize 883 an GSSContext object with this token to create a new context. Once a 884 context has been exported, the GSSContext object is invalidated and 885 is no longer available. 887 4.12. Error Reporting 889 RFC 2743 [RFC2743] defined the usage of major and minor status values 890 for the signaling of GSS-API errors. The major code, also called GSS 891 status code, is used to signal errors at the GSS-API level, 892 independent of the underlying mechanism(s). The minor status value 893 or Mechanism status code, is a mechanism-defined error value 894 indicating a mechanism-specific error code. 896 Java GSS-API uses exceptions implemented by the GSSException class to 897 signal both minor and major error values. Both mechanism-specific 898 errors and GSS-API level errors are signaled through instances of 899 this class. The usage of exceptions replaces the need for major and 900 minor codes to be used within the API calls. The GSSException class 901 also contains methods to obtain textual representations for both the 902 major and minor values, which is equivalent to the functionality of 903 gss_display_status. 905 4.12.1. GSS Status Codes 907 GSS status codes indicate errors that are independent of the 908 underlying mechanism(s) used to provide the security service. The 909 errors that can be indicated via a GSS status code are generic API 910 routine errors (errors that are defined in the GSS-API 911 specification). These bindings take advantage of the Java exceptions 912 mechanism, thus, eliminating the need for calling errors. 914 A GSS status code indicates a single fatal generic API error from the 915 routine that has thrown the GSSException. Using exceptions announces 916 that a fatal error has occurred during the execution of the method. 917 The GSS-API operational model also allows for the signaling of 918 supplementary status information from the per-message calls. These 919 need to be handled as return values since using exceptions is not 920 appropriate for informatory or warning-like information. The methods 921 that are capable of producing supplementary information are the two 922 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 923 These methods fill the supplementary status codes in the MessageProp 924 object that was passed in. 926 A GSSException object, along with providing the functionality for 927 setting of the various error codes and translating them into textual 928 representation, also contains the definitions of all the numeric 929 error values. The following table lists the definitions of error 930 codes: 932 Table: GSS Status Codes 934 +------------------------+--------+---------------------------------+ 935 | Name | Value | Meaning | 936 +------------------------+--------+---------------------------------+ 937 | BAD_BINDINGS | 1 | Incorrect channel bindings were | 938 | | | supplied. | 939 | | | | 940 | BAD_MECH | 2 | An unsupported mechanism was | 941 | | | requested. | 942 | | | | 943 | BAD_NAME | 3 | An invalid name was supplied. | 944 | | | | 945 | BAD_NAMETYPE | 4 | A supplied name was of an | 946 | | | unsupported type. | 947 | | | | 948 | BAD_STATUS | 5 | An invalid status code was | 949 | | | supplied. | 950 | | | | 951 | BAD_MIC | 6 | A token had an invalid MIC. | 952 | | | | 953 | CONTEXT_EXPIRED | 7 | The context has expired. | 954 | | | | 955 | CREDENTIALS_EXPIRED | 8 | The referenced credentials have | 956 | | | expired. | 957 | | | | 958 | DEFECTIVE_CREDENTIAL | 9 | A supplied credential was | 959 | | | invalid. | 960 | | | | 961 | DEFECTIVE_TOKEN | 10 | A supplied token was invalid. | 962 | | | | 963 | FAILURE | 11 | Miscellaneous failure, | 964 | | | unspecified at the GSS-API | 965 | | | level. | 966 | | | | 967 | NO_CONTEXT | 12 | Invalid context has been | 968 | | | supplied. | 969 | | | | 970 | NO_CRED | 13 | No credentials were supplied, | 971 | | | or the credentials were | 972 | | | unavailable or inaccessible. | 973 | | | | 974 | BAD_QOP | 14 | The quality-of-protection (QOP) | 975 | | | requested could not be | 976 | | | provided. | 977 | | | | 978 | UNAUTHORIZED | 15 | The operation is forbidden by | 979 | | | the local security policy. | 980 | | | | 981 | UNAVAILABLE | 16 | The operation or option is | 982 | | | unavailable. | 983 | | | | 984 | DUPLICATE_ELEMENT | 17 | The requested credential | 985 | | | element already exists. | 986 | | | | 987 | NAME_NOT_MN | 18 | The provided name was not a | 988 | | | mechanism name. | 989 +------------------------+--------+---------------------------------+ 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 | 1001 | | | an earlier version. | 1002 | | | | 1003 | OLD_TOKEN | 20 | The token's validity period | 1004 | | | has expired. | 1005 | | | | 1006 | UNSEQ_TOKEN | 21 | A later token has already been | 1007 | | | processed. | 1008 | | | | 1009 | GAP_TOKEN | 22 | The expected token was not | 1010 | | | received. | 1011 +-----------------------+----------+--------------------------------+ 1013 The GSS major status code of FAILURE is used to indicate that the 1014 underlying mechanism detected an error for which no specific GSS 1015 status code is defined. The mechanism-specific status code can 1016 provide more details about the error. 1018 The different major status codes that can be contained in the 1019 GSSException object thrown by the methods in this specification are 1020 the same as the major status codes returned by the corresponding 1021 calls in RFC 2743 [RFC2743]. 1023 4.12.2. Mechanism-Specific Status Codes 1025 Mechanism-specific status codes are communicated in two ways, they 1026 are part of any GSSException thrown from the mechanism-specific layer 1027 to signal a fatal error, or they are part of the MessageProp object 1028 that the per-message calls use to signal non-fatal errors. 1030 A default value of 0 in either the GSSException object or the 1031 MessageProp object will be used to represent the absence of any 1032 mechanism-specific status code. 1034 4.12.3. Supplementary Status Codes 1036 Supplementary status codes are confined to the per-message methods of 1037 the GSSContext interface. Because of the informative nature of these 1038 errors it is not appropriate to use exceptions to signal them. 1039 Instead, the per-message operations of the GSSContext interface 1040 return these values in a MessageProp object. 1042 The MessageProp class defines query methods that return boolean 1043 values indicating the following supplementary states: 1045 Table: Supplementary Status Methods 1047 +---------------------------+---------------------------------------+ 1048 | Method Name | Meaning when "true" is returned | 1049 +---------------------------+---------------------------------------+ 1050 | isDuplicateToken | The token was a duplicate of an | 1051 | | earlier token. | 1052 | | | 1053 | isOldToken | The token's validity period has | 1054 | | expired. | 1055 | | | 1056 | isUnseqToken | A later token has already been | 1057 | | processed. | 1058 | | | 1059 | isGapToken | An expected per-message token was not | 1060 | | received. | 1061 +---------------------------+---------------------------------------+ 1063 A "true" return value for any of the above methods indicates that the 1064 token exhibited the specified property. The application must 1065 determine the appropriate course of action for these supplementary 1066 values. They are not treated as errors by the GSS-API. 1068 4.13. Names 1070 A name is used to identify a person or entity. GSS-API authenticates 1071 the relationship between a name and the entity claiming the name. 1073 Since different authentication mechanisms may employ different 1074 namespaces for identifying their principals, GSS-API's naming support 1075 is necessarily complex in multi-mechanism environments (or even in 1076 some single-mechanism environments where the underlying mechanism 1077 supports multiple namespaces). 1079 Two distinct conceptual representations are defined for names: 1081 1) A GSS-API form represented by implementations of the GSSName 1082 interface: A single GSSName object may contain multiple names from 1083 different namespaces, but all names should refer to the same 1084 entity. An example of such an internal name would be the name 1085 returned from a call to the getName method of the GSSCredential 1086 interface, when applied to a credential containing credential 1087 elements for multiple authentication mechanisms employing 1088 different namespaces. This GSSName object will contain a distinct 1089 name for the entity for each authentication mechanism. 1091 For GSS-API implementations supporting multiple namespaces, 1092 GSSName implementations must contain sufficient information to 1093 determine the namespace to which each primitive name belongs. 1095 2) Mechanism-specific contiguous byte array and string forms: 1096 Different GSSName initialization methods are provided to handle 1097 both byte array and string formats and to accommodate various 1098 calling applications and name types. These formats are capable of 1099 containing only a single name (from a single namespace). 1100 Contiguous string names are always accompanied by an object 1101 identifier specifying the namespace to which the name belongs, and 1102 their format is dependent on the authentication mechanism that 1103 employs that name. The string name forms are assumed to be 1104 printable, and may therefore be used by GSS-API applications for 1105 communication with their users. The byte array name formats are 1106 assumed to be in non-printable formats (e.g., the byte array 1107 returned from the export method of the GSSName interface). 1109 A GSSName object can be converted to a contiguous representation by 1110 using the toString method. This will guarantee that the name will be 1111 converted to a printable format. Different initialization methods in 1112 the GSSName interface are defined allowing support for multiple 1113 syntaxes for each supported namespace, and allowing users the freedom 1114 to choose a preferred name representation. The toString method 1115 should use an implementation-chosen printable syntax for each 1116 supported name type. To obtain the printable name type, 1117 getStringNameType method can be used. 1119 There is no guarantee that calling the toString method on the GSSName 1120 interface will produce the same string form as the original imported 1121 string name. Furthermore, it is possible that the name was not even 1122 constructed from a string representation. The same applies to 1123 namespace identifiers, which may not necessarily survive unchanged 1124 after a journey through the internal name form. An example of this 1125 might be a mechanism that authenticates X.500 names, but provides an 1126 algorithmic mapping of Internet DNS names into X.500. That 1127 mechanism's implementation of GSSName might, when presented with a 1128 DNS name, generate an internal name that contained both the original 1129 DNS name and the equivalent X.500 name. Alternatively, it might only 1130 store the X.500 name. In the latter case, the toString method of 1131 GSSName would most likely generate a printable X.500 name, rather 1132 than the original DNS name. 1134 The context acceptor can obtain a GSSName object representing the 1135 entity performing the context initiation (through the usage of 1136 getSrcName method). Since this name has been authenticated by a 1137 single mechanism, it contains only a single name (even if the 1138 internal name presented by the context initiator to the GSSContext 1139 object had multiple components). Such names are termed internal- 1140 mechanism names (or MNs), and the names emitted by GSSContext 1141 interface in the getSrcName and getTargName are always of this type. 1142 Since some applications may require MNs without wanting to incur the 1143 overhead of an authentication operation, creation methods are 1144 provided that take not only the name buffer and name type, but also 1145 the mechanism oid for which this name should be created. When 1146 dealing with an existing GSSName object, the canonicalize method may 1147 be invoked to convert a general internal name into an MN. 1149 GSSName objects can be compared using their equal method, which 1150 returns "true" if the two names being compared refer to the same 1151 entity. This is the preferred way to perform name comparisons 1152 instead of using the printable names that a given GSS-API 1153 implementation may support. Since GSS-API assumes that all primitive 1154 names contained within a given internal name refer to the same 1155 entity, equal can return "true" if the two names have at least one 1156 primitive name in common. If the implementation embodies knowledge 1157 of equivalence relationships between names taken from different 1158 namespaces, this knowledge may also allow successful comparisons of 1159 internal names containing no overlapping primitive elements. 1161 When used in large access control lists, the overhead of creating a 1162 GSSName object on each name and invoking the equal method on each 1163 name from the Access Control List (ACL) may be prohibitive. As an 1164 alternative way of supporting this case, GSS-API defines a special 1165 form of the contiguous byte array name, which may be compared 1166 directly (byte by byte). Contiguous names suitable for comparison 1167 are generated by the export method. Exported names may be re- 1168 imported by using the byte array constructor and specifying the 1169 NT_EXPORT_NAME as the name type object identifier. The resulting 1170 GSSName name will also be a MN. 1172 The GSSName interface defines public static Oid objects representing 1173 the standard name types. Structurally, an exported name object 1174 consists of a header containing an OID identifying the mechanism that 1175 authenticated the name, and a trailer containing the name itself, 1176 where the syntax of the trailer is defined by the individual 1177 mechanism specification. Detailed description of the format is 1178 specified in the language-independent GSS-API specification 1179 [RFC2743]. 1181 Note that the results obtained by using the equals method will in 1182 general be different from those obtained by invoking canonicalize and 1183 export, and then comparing the byte array output. The first series 1184 of operation determines whether two (unauthenticated) names identify 1185 the same principal; the second whether a particular mechanism would 1186 authenticate them as the same principal. These two operations will 1187 in general give the same results only for MNs. 1189 It is important to note that the above are guidelines as to how 1190 GSSName implementations should behave, and are not intended to be 1191 specific requirements of how name objects must be implemented. The 1192 mechanism designers are free to decide on the details of their 1193 implementations of the GSSName interface as long as the behavior 1194 satisfies the above guidelines. 1196 4.14. Channel Bindings 1198 GSS-API supports the use of user-specified tags to identify a given 1199 context to the peer application. These tags are intended to be used 1200 to identify the particular communications channel that carries the 1201 context. Channel bindings are communicated to the GSS-API using the 1202 ChannelBinding object. The application may use byte arrays to 1203 specify the application data to be used in the channel binding as 1204 well as using instances of the InetAddress. The InetAddress for the 1205 initiator and/or acceptor can be used within an instance of a 1206 ChannelBinding. ChannelBinding can be set for the GSSContext object 1207 using the setChannelBinding method before the first call to init or 1208 accept has been performed. Unless the setChannelBinding method has 1209 been used to set the ChannelBinding for a GSSContext object, "null" 1210 ChannelBinding will be assumed. InetAddress is currently the only 1211 address type defined within the Java platform and as such, it is the 1212 only one supported within the ChannelBinding class. Applications 1213 that use other types of addresses can include them as part of the 1214 application-specific data. 1216 Conceptually, the GSS-API concatenates the initiator and acceptor 1217 address information, and the application-supplied byte array to form 1218 an octet-string. The mechanism calculates a Message Integrity Code 1219 (MIC) over this octet-string and binds the MIC to the context 1220 establishment token emitted by the init method of the GSSContext 1221 interface. The same bindings are set by the context acceptor for its 1222 GSSContext object and during processing of the accept method, a MIC 1223 is calculated in the same way. The calculated MIC is compared with 1224 that found in the token, and if the MICs differ, accept will throw a 1225 GSSException with the major code set to BAD_BINDINGS, and the context 1226 will not be established. Some mechanisms may include the actual 1227 channel binding data in the token (rather than just a MIC); 1228 applications should therefore not use confidential data as channel- 1229 binding components. 1231 Individual mechanisms may impose additional constraints on addresses 1232 that may appear in channel bindings. For example, a mechanism may 1233 verify that the initiator address field of the channel binding 1234 contains the correct network address of the host system. Portable 1235 applications should therefore ensure that they either provide correct 1236 information for the address fields, or omit the setting of the 1237 addressing information. 1239 4.15. Stream Objects 1241 The context object provides overloaded methods that use input and 1242 output streams as the means to convey authentication and per-message 1243 GSS-API tokens. It is important to note that the streams are 1244 expected to contain the usual GSS-API tokens, which would otherwise 1245 be handled through the usage of byte arrays. The tokens are expected 1246 to have a definite start and an end. The callers are responsible for 1247 ensuring that the supplied streams will not block, or expect to block 1248 until a full token is processed by the GSS-API method. Only a single 1249 GSS-API token will be processed per invocation of the stream-based 1250 method. 1252 The usage of streams allows the callers to have control and 1253 management of the supplied buffers. Because streams are non- 1254 primitive objects, the callers can make the streams as complicated or 1255 as simple as desired simply by using the streams defined in the 1256 java.io package or creating their own through the use of inheritance. 1257 This will allow for the application's greatest flexibility. 1259 4.16. Optional Parameters 1261 Whenever the application wishes to omit an optional parameter the 1262 "null" value shall be used. The detailed method descriptions 1263 indicate which parameters are optional. Method overloading has also 1264 been used as a technique to indicate default parameters. 1266 5. Introduction to GSS-API Classes and Interfaces 1268 This section presents a brief description of the classes and 1269 interfaces that constitute the GSS-API. The implementations of these 1270 are obtained from the CLASSPATH defined by the application. If Java 1271 GSS becomes part of the standard Java APIs, then these classes will 1272 be available by default on all systems as part of the JRE's system 1273 classes. 1275 This section also shows the corresponding RFC 2743 [RFC2743] 1276 functionality implemented by each of the classes. Detailed 1277 description of these classes and their methods is presented in 1278 section 6 1280 5.1. GSSManager Class 1282 This abstract class serves as a factory to instantiate 1283 implementations of the GSS-API interfaces and also provides methods 1284 to make queries about underlying security mechanisms. 1286 A default implementation can be obtained using the static method 1287 getInstance(). Applications that desire to provide their own 1288 implementation of the GSSManager class can simply extend the abstract 1289 class themselves. 1291 This class contains equivalents of the following RFC 2743 [RFC2743] 1292 routines: 1294 +------------------------------+---------------------+--------------+ 1295 | RFC 2743 Routine | Function | Section(s) | 1296 +------------------------------+---------------------+--------------+ 1297 | gss_import_name | Create an internal | 6.1.6- 6.1.9 | 1298 | | name from the | | 1299 | | supplied | | 1300 | | information. | | 1301 | | | | 1302 | gss_acquire_cred | Acquire credential | 6.1.10- | 1303 | | for use. | 6.1.12 | 1304 | | | | 1305 | gss_import_sec_context | Create a previously | 6.1.15 | 1306 | | exported context. | | 1307 | | | | 1308 | gss_indicate_mechs | List the mechanisms | 6.1.3 | 1309 | | supported by this | | 1310 | | GSS-API | | 1311 | | implementation. | | 1312 | | | | 1313 | gss_inquire_mechs_for_name | List the mechanisms | 6.1.5 | 1314 | | supporting the | | 1315 | | specified name | | 1316 | | type. | | 1317 | | | | 1318 | gss_inquire_names_for_mech | List the name types | 6.1.4 | 1319 | | supported by the | | 1320 | | specified | | 1321 | | mechanism. | | 1322 +------------------------------+---------------------+--------------+ 1324 5.2. GSSName Interface 1326 GSS-API names are represented in the Java bindings through the 1327 GSSName interface. Different name formats and their definitions are 1328 identified with Universal Object Identifiers (oids). The format of 1329 the names can be derived based on the unique oid of each name type. 1330 The following GSS-API routines are provided by the GSSName interface: 1332 +---------------------------+------------------------+--------------+ 1333 | RFC 2743 Routine | Function | Section(s) | 1334 +---------------------------+------------------------+--------------+ 1335 | gss_display_name | Covert internal name | 6.2.7 | 1336 | | representation to text | | 1337 | | format. | | 1338 | | | | 1339 | gss_compare_name | Compare two internal | 6.2.3, 6.2.4 | 1340 | | names. | | 1341 | | | | 1342 | gss_release_name | Release resources | N/A | 1343 | | associated with the | | 1344 | | internal name. | | 1345 | | | | 1346 | gss_canonicalize_name | Convert an internal | 6.2.5 | 1347 | | name to a mechanism | | 1348 | | name. | | 1349 | | | | 1350 | gss_export_name | Convert a mechanism | 6.2.6 | 1351 | | name to export format. | | 1352 | | | | 1353 | gss_duplicate_name | Create a copy of the | N/A | 1354 | | internal name. | | 1355 +---------------------------+------------------------+--------------+ 1357 The gss_release_name call is not provided as Java does its own 1358 garbage collection. The gss_duplicate_name call is also redundant; 1359 the GSSName interface has no mutator methods that can change the 1360 state of the object so it is safe for sharing across threads. 1362 5.3. GSSCredential Interface 1364 The GSSCredential interface is responsible for the encapsulation of 1365 GSS-API credentials. Credentials identify a single entity and 1366 provide the necessary cryptographic information to enable the 1367 creation of a context on behalf of that entity. A single credential 1368 may contain multiple mechanism-specific credentials, each referred to 1369 as a credential element. The GSSCredential interface provides the 1370 functionality of the following GSS-API routines: 1372 +----------------------------+----------------------+---------------+ 1373 | RFC 2743 Routine | Function | Section(s) | 1374 +----------------------------+----------------------+---------------+ 1375 | gss_add_cred | Constructs | 6.3.12 | 1376 | | credentials | | 1377 | | incrementally. | | 1378 | | | | 1379 | gss_inquire_cred | Obtain information | 6.3.4- 6.3.11 | 1380 | | about credential. | | 1381 | | | | 1382 | gss_inquire_cred_by_mech | Obtain per-mechanism | 6.3.5- 6.3.10 | 1383 | | information about a | | 1384 | | credential. | | 1385 | | | | 1386 | gss_release_cred | Dispose of | 6.3.3 | 1387 | | credentials after | | 1388 | | use. | | 1389 +----------------------------+----------------------+---------------+ 1391 5.4. GSSContext Interface 1393 This interface encapsulates the functionality of context-level calls 1394 required for security context establishment and management between 1395 peers as well as the per-message services offered to applications. A 1396 context is established between a pair of peers and allows the usage 1397 of security services on a per-message basis on application data. It 1398 is created over a single security mechanism. The GSSContext 1399 interface provides the functionality of the following GSS-API 1400 routines: 1402 +--------------------------+--------------------------+-------------+ 1403 | RFC 2743 Routine | Function | Section(s) | 1404 +--------------------------+--------------------------+-------------+ 1405 | gss_init_sec_context | Initiate the creation of | 6.4.3- | 1406 | | a security context with | 6.4.6 | 1407 | | a peer. | | 1408 | | | | 1409 | gss_accept_sec_context | Accept a security | 6.4.7- | 1410 | | context initiated by a | 6.4.10 | 1411 | | peer. | | 1412 | | | | 1413 | gss_delete_sec_context | Destroy a security | 6.4.12 | 1414 | | context. | | 1415 | | | | 1416 | gss_context_time | Obtain remaining context | 6.4.41 | 1417 | | time. | | 1418 | | | | 1419 | gss_inquire_context | Obtain context | 6.4.32- | 1420 | | characteristics. | 6.4.46 | 1421 | | | | 1422 | gss_wrap_size_limit | Determine token-size | 6.4.13 | 1423 | | limit for gss_wrap. | | 1424 | | | | 1425 | gss_export_sec_context | Transfer security | 6.4.22 | 1426 | | context to another | | 1427 | | process. | | 1428 | | | | 1429 | gss_get_mic | Calculate a | 6.4.18, | 1430 | | cryptographic Message | 6.4.19 | 1431 | | Integrity Code (MIC) for | | 1432 | | a message. | | 1433 | | | | 1434 | gss_verify_mic | Verify integrity on a | 6.4.20, | 1435 | | received message. | 6.4.21 | 1436 | | | | 1437 | gss_wrap | Attach a MIC to a | 6.4.14, | 1438 | | message and optionally | 6.4.15 | 1439 | | encrypt the message | | 1440 | | content. | | 1441 | | | | 1442 | gss_unwrap | Obtain a previously | 6.4.16, | 1443 | | wrapped application | 6.4.17 | 1444 | | message verifying its | | 1445 | | integrity and optionally | | 1446 | | decrypting it. | | 1447 +--------------------------+--------------------------+-------------+ 1449 The functionality offered by the gss_process_context_token routine 1450 has not been included in the Java bindings specification. The 1451 corresponding functionality of gss_delete_sec_context has also been 1452 modified to not return any peer tokens. This has been proposed in 1453 accordance to the recommendations stated in RFC 2743 [RFC2743]. 1454 GSSContext does offer the functionality of destroying the locally 1455 stored context information. 1457 5.5. MessageProp Class 1459 This helper class is used in the per-message operations on the 1460 context. An instance of this class is created by the application and 1461 then passed into the per-message calls. In some cases, the 1462 application conveys information to the GSS-API implementation through 1463 this object and in other cases the GSS-API returns information to the 1464 application by setting it in this object. See the description of the 1465 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1466 GSSContext interfaces for details. 1468 5.6. GSSException Class 1470 Exceptions are used in the Java bindings to signal fatal errors to 1471 the calling applications. This replaces the major and minor codes 1472 used in the C-bindings specification as a method of signaling 1473 failures. The GSSException class handles both minor and major codes, 1474 as well as their translation into textual representation. All GSS- 1475 API methods are declared as throwing this exception. 1477 +------------------------+--------------------------+---------------+ 1478 | RFC 2743 Routine | Function | Section | 1479 +------------------------+--------------------------+---------------+ 1480 | gss_display_status | Retrieve textual | 6.8.5, 6.8.6, | 1481 | | representation of error | 6.8.9, 6.8.10 | 1482 | | codes. | | 1483 +------------------------+--------------------------+---------------+ 1485 5.7. Oid Class 1487 This utility class is used to represent Universal Object Identifiers 1488 and their associated operations. GSS-API uses object identifiers to 1489 distinguish between security mechanisms and name types. This class, 1490 aside from being used whenever an object identifier is needed, 1491 implements the following GSS-API functionality: 1493 +-------------------------------+------------------------+----------+ 1494 | RFC 2743 Routine | Function | Section | 1495 +-------------------------------+------------------------+----------+ 1496 | gss_test_oid_set_member | Determine if the | 6.7.5 | 1497 | | specified oid is part | | 1498 | | of a set of oids. | | 1499 +-------------------------------+------------------------+----------+ 1501 5.8. ChannelBinding Class 1503 An instance of this class is used to specify channel binding 1504 information to the GSSContext object before the start of a security 1505 context establishment. The application may use a byte array to 1506 specify application data to be used in the channel binding as well as 1507 to use instances of the InetAddress. InetAddress is currently the 1508 only address type defined within the Java platform and as such, it is 1509 the only one supported within the ChannelBinding class. Applications 1510 that use other types of addresses can include them as part of the 1511 application data. 1513 6. Detailed GSS-API Class Description 1515 This section lists a detailed description of all the public methods 1516 that each of the GSS-API classes and interfaces must provide. 1518 6.1. public abstract class GSSManager 1520 The GSSManager class is an abstract class that serves as a factory 1521 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1522 also provides methods for applications to determine what mechanisms 1523 are available from the GSS implementation and what name types these 1524 mechanisms support. An instance of the default GSSManager subclass 1525 may be obtained through the static method getInstance(), but 1526 applications are free to instantiate other subclasses of GSSManager. 1528 All but one method in this class are declared abstract. This means 1529 that subclasses have to provide the complete implementation for those 1530 methods. The only exception to this is the static method 1531 getInstance(), which will have platform-specific code to return an 1532 instance of the default subclass. 1534 Platform providers of GSS are required not to add any constructors to 1535 this class, private, public, or protected. This will ensure that all 1536 subclasses invoke only the default constructor provided to the base 1537 class by the compiler. 1539 A subclass extending the GSSManager abstract class may be implemented 1540 as a modular provider-based layer that utilizes some well-known 1541 service provider specification. The GSSManager API provides the 1542 application with methods to set provider preferences on such an 1543 implementation. These methods also allow the implementation to throw 1544 a well-defined exception in case provider-based configuration is not 1545 supported. Applications that expect to be portable should be aware 1546 of this and recover cleanly by catching the exception. 1548 It is envisioned that there will be three most common ways in which 1549 providers will be used: 1551 1) The application does not care about what provider is used (the 1552 default case). 1554 2) The application wants a particular provider to be used 1555 preferentially, either for a particular mechanism or all the time, 1556 irrespective of the mechanism. 1558 3) The application wants to use the locally configured providers as 1559 far as possible, but if support is missing for one or more 1560 mechanisms, then it wants to fall back on its own provider. 1562 The GSSManager class has two methods that enable these modes of 1563 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1564 have the effect of creating an ordered list of pairs 1565 where each pair indicates a preference of provider for a given oid. 1567 The use of these methods does not require any knowledge of whatever 1568 service provider specification the GSSManager subclass follows. It 1569 is hoped that these methods will serve the needs of most 1570 applications. Additional methods may be added to an extended 1571 GSSManager that could be part of a service provider specification 1572 that is standardized later. 1574 6.1.1. Example Code 1576 1577 GSSManager mgr = GSSManager.getInstance(); 1579 // What mechs are available to us? 1581 Oid[] supportedMechs = mgr.getMechs(); 1583 // Set a preference for the provider to be used when support 1584 // is needed for the mechanisms: 1585 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1587 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1588 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1590 Provider p = (Provider) (new com.foo.security.Provider()); 1592 mgr.addProviderAtFront(p, krb); 1593 mgr.addProviderAtFront(p, spkm1); 1595 // What name types does this spkm implementation support? 1596 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1597 1599 6.1.2. getInstance 1601 public static GSSManager getInstance() 1603 Returns the default GSSManager implementation. 1605 6.1.3. getMechs 1607 public abstract Oid[] getMechs() 1609 Returns an array of Oid objects indicating the mechanisms available 1610 to GSS-API callers. A "null" value is returned when no mechanism are 1611 available (an example of this would be when mechanism are dynamically 1612 configured, and currently no mechanisms are installed). 1614 6.1.4. getNamesForMech 1616 public abstract Oid[] getNamesForMech(Oid mech) 1617 throws GSSException 1619 Returns name type Oid's supported by the specified mechanism. 1621 mech The Oid object for the mechanism to query. 1623 6.1.5. getMechsForName 1625 public abstract Oid[] getMechsForName(Oid nameType) 1627 Returns an array of Oid objects corresponding to the mechanisms that 1628 support the specific name type. "null" is returned when no mechanisms 1629 are found to support the specified name type. 1631 nameType The Oid object for the name type. 1633 6.1.6. createName 1635 public abstract GSSName createName(String nameStr, Oid nameType) 1636 throws GSSException 1638 Factory method to convert a contiguous string name from the specified 1639 namespace to a GSSName object. In general, the GSSName object 1640 created will not be an MN; two examples that are exceptions to this 1641 are when the namespace type parameter indicates NT_EXPORT_NAME or 1642 when the GSS-API implementation is not multi-mechanism. 1644 nameStr The string representing a printable form of the 1645 name tocreate. 1647 nameType The Oid specifying the namespace of the printable 1648 nameis supplied. Note that nameType serves to 1649 describe and qualify the interpretation of the 1650 input nameStr, it does not necessarily imply a 1651 type for the output GSSName implementation. The 1652 "null" value can be used to specify that a 1653 mechanism-specific default printable syntax 1654 should be assumed by each mechanism that examines 1655 nameStr. 1657 6.1.7. createName 1659 public abstract GSSName createName(byte[] name, Oid nameType) 1660 throws GSSException 1662 Factory method to convert a contiguous byte array containing a name 1663 from the specified namespace to a GSSName object. In general, the 1664 GSSName object created will not be an MN; two examples that are 1665 exceptions to this are when the namespace type parameter indicates 1666 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1667 mechanism. 1669 name The byte array containing the name to create. 1671 nameType The Oid specifying the namespace of the name 1672 supplied inthe byte array. Note that nameType 1673 serves to describe and qualify the interpretation 1674 of the input name byte array; it does not 1675 necessarily imply a type for the output GSSName 1676 implementation. The "null" value can be used to 1677 specify that a mechanism-specific default syntax 1678 should be assumed by each mechanism that examines 1679 the byte array. 1681 6.1.8. createName 1683 public abstract GSSName createName(String nameStr, Oid nameType, 1684 Oid mech) throws GSSException 1686 Factory method to convert a contiguous string name from the specified 1687 namespace to a GSSName object that is a mechanism name (MN). In 1688 other words, this method is a utility that does the equivalent of two 1689 steps: the createName described in section 6.1.6, and then also the 1690 GSSName.canonicalize() described in section 6.2.5. 1692 nameStr The string representing a printable form of the 1693 name tocreate. 1695 nameType The Oid specifying the namespace of the printable 1696 namesupplied. Note that nameType serves to 1697 describe and qualify the interpretation of the 1698 input nameStr; it does not necessarily imply a 1699 type for the output GSSName implementation. The 1700 "null" value can be used to specify that a 1701 mechanism-specific default printable syntax 1702 should be assumed when the mechanism examines 1703 nameStr. 1705 mech Oid specifying the mechanism for which this name 1706 should becreated. 1708 6.1.9. createName 1710 public abstract GSSName createName(byte[] name, Oid nameType, 1711 Oid mech) throws GSSException 1713 Factory method to convert a contiguous byte array containing a name 1714 from the specified namespace to a GSSName object that is an MN. In 1715 other words, this method is a utility that does the equivalent of two 1716 steps: the createName described in section 6.1.7, and then also the 1717 GSSName.canonicalize() described in section 6.2.5. 1719 name The byte array representing the name to create. 1721 nameType The Oid specifying the namespace of the name 1722 supplied inthe byte array. Note that nameType 1723 serves to describe and qualify the interpretation 1724 of the input name byte array, it does not 1725 necessarily imply a type for the output GSSName 1726 implementation. The "null" value can be used to 1727 specify that a mechanism-specific default syntax 1728 should be assumed by each mechanism that examines 1729 the byte array. 1731 mech Oid specifying the mechanism for which this name 1732 should becreated. 1734 6.1.10. createCredential 1736 public abstract GSSCredential createCredential(int usage) 1737 throws GSSException 1739 Factory method for acquiring default credentials. This will cause 1740 the GSS-API to use system-specific defaults for the set of 1741 mechanisms, name, and a DEFAULT lifetime. 1743 usage The intended usage for this credential object. 1744 The value ofthis parameter must be one of: 1746 GSSCredential.INITIATE_AND_ACCEPT(0), 1747 GSSCredential.INITIATE_ONLY(1), or 1748 GSSCredential.ACCEPT_ONLY(2) 1750 6.1.11. createCredential 1752 public abstract GSSCredential createCredential(GSSName aName, 1753 int lifetime, Oid mech, int usage) 1754 throws GSSException 1756 Factory method for acquiring a single mechanism credential. 1758 aName Name of the principal for whom this credential is 1759 to beacquired. Use "null" to specify the default 1760 principal. 1762 lifetime The number of seconds that credentials should 1763 remainvalid. Use 1764 GSSCredential.INDEFINITE_LIFETIME to request that 1765 the credentials have the maximum permitted 1766 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1767 request default credential lifetime. 1769 mech The oid of the desired mechanism. Use "(Oid) 1770 null" torequest the default mechanism(s). 1772 usage The intended usage for this credential object. 1773 The value ofthis parameter must be one of: 1775 GSSCredential.INITIATE_AND_ACCEPT(0), 1776 GSSCredential.INITIATE_ONLY(1), or 1777 GSSCredential.ACCEPT_ONLY(2) 1779 6.1.12. createCredential 1781 public abstract GSSCredential createCredential(GSSName aName, 1782 int lifetime, Oid[] mechs, int usage) 1783 throws GSSException 1785 Factory method for acquiring credentials over a set of mechanisms. 1786 Acquires credentials for each of the mechanisms specified in the 1787 array called mechs. To determine the list of mechanisms' for which 1788 the acquisition of credentials succeeded, the caller should use the 1789 GSSCredential.getMechs() method. 1791 aName Name of the principal for whom this credential is 1792 to beacquired. Use "null" to specify the default 1793 principal. 1795 lifetime The number of seconds that credentials should 1796 remainvalid. Use 1797 GSSCredential.INDEFINITE_LIFETIME to request that 1798 the credentials have the maximum permitted 1799 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1800 request default credential lifetime. 1802 mechs The array of mechanisms over which the credential 1803 is to beacquired. Use "(Oid[]) null" for 1804 requesting a system-specific default set of 1805 mechanisms. 1807 usage The intended usage for this credential object. 1808 The value ofthis parameter must be one of: 1810 GSSCredential.INITIATE_AND_ACCEPT(0), 1811 GSSCredential.INITIATE_ONLY(1), or 1812 GSSCredential.ACCEPT_ONLY(2) 1814 6.1.13. createContext 1816 public abstract GSSContext createContext(GSSName peer, Oid mech, 1817 GSSCredential myCred, int lifetime) 1818 throws GSSException 1820 Factory method for creating a context on the initiator's side. 1821 Context flags may be modified through the mutator methods prior to 1822 calling GSSContext.initSecContext(). 1824 peer Name of the target peer. 1826 mech Oid of the desired mechanism. Use "(Oid) null" 1827 to requestthe default mechanism. 1829 myCred Credentials of the initiator. Use "null" to act 1830 as adefault initiator principal. 1832 lifetime The request lifetime, in seconds, for the 1833 context. UseGSSContext.INDEFINITE_LIFETIME and 1834 GSSContext.DEFAULT_LIFETIME to request indefinite 1835 or default context lifetime. 1837 6.1.14. createContext 1839 public abstract GSSContext createContext(GSSCredential myCred) 1840 throws GSSException 1842 Factory method for creating a context on the acceptor' side. The 1843 context's properties will be determined from the input token supplied 1844 to the accept method. 1846 myCred Credentials for the acceptor. Use "null" to act 1847 as adefault acceptor principal. 1849 6.1.15. createContext 1851 public abstract GSSContext createContext(byte[] interProcessToken) 1852 throws GSSException 1854 Factory method for creating a previously exported context. The 1855 context properties will be determined from the input token and can't 1856 be modified through the set methods. 1858 interProcessToken The token previously emitted from the 1859 exportmethod. 1861 6.1.16. addProviderAtFront 1863 public abstract void addProviderAtFront(Provider p, Oid mech) 1864 throws GSSException 1866 This method is used to indicate to the GSSManager that the 1867 application would like a particular provider to be used ahead of all 1868 others when support is desired for the given mechanism. When a value 1869 of "null" is used instead of an Oid for the mechanism, the GSSManager 1870 must use the indicated provider ahead of all others no matter what 1871 the mechanism is. Only when the indicated provider does not support 1872 the needed mechanism should the GSSManager move on to a different 1873 provider. 1875 Calling this method repeatedly preserves the older settings but 1876 lowers them in preference thus forming an ordered list of provider 1877 and Oid pairs that grows at the top. 1879 Calling addProviderAtFront with a null Oid will remove all previous 1880 preferences that were set for this provider in the GSSManager 1881 instance. Calling addProviderAtFront with a non-null Oid will remove 1882 any previous preference that was set using this mechanism and this 1883 provider together. 1885 If the GSSManager implementation does not support an SPI with a 1886 pluggable provider architecture, it should throw a GSSException with 1887 the status code GSSException.UNAVAILABLE to indicate that the 1888 operation is unavailable. 1890 p The provider instance that should be used 1891 whenever support isneeded for mech. 1893 mech The mechanism for which the provider is being 1894 set. 1896 6.1.17. Example Code 1898 Suppose an application desired that the provider A always be checked 1899 first when any mechanism is needed, it would call: 1901 1902 GSSManager mgr = GSSManager.getInstance(); 1903 // mgr may at this point have its own pre-configured list 1904 // of provider preferences. The following will prepend to 1905 // any such list: 1907 mgr.addProviderAtFront(A, null); 1908 1910 Now if it also desired that the mechanism of Oid m1 always be 1911 obtained from the provider B before the previously set A was checked, 1912 it would call: 1914 1915 mgr.addProviderAtFront(B, m1); 1916 1918 The GSSManager would then first check with B if m1 was needed. In 1919 case B did not provide support for m1, the GSSManager would continue 1920 on to check with A. If any mechanism m2 is needed where m2 is 1921 different from m1, then the GSSManager would skip B and check with A 1922 directly. 1924 Suppose, at a later time, the following call is made to the same 1925 GSSManager instance: 1927 1928 mgr.addProviderAtFront(B, null) 1929 1931 then the previous setting with the pair (B, m1) is subsumed by this 1932 and should be removed. Effectively, the list of preferences now 1933 becomes {(B, null), (A, null), ... //followed by the pre-configured 1934 list. 1936 Please note, however, that the following call: 1938 1939 mgr.addProviderAtFront(A, m3) 1940 1942 does not subsume the previous setting of (A, null), and the list will 1943 effectively become {(A, m3), (B, null), (A, null), ...} 1945 6.1.18. addProviderAtEnd 1947 public abstract void addProviderAtEnd(Provider p, Oid mech) 1948 throws GSSException 1950 This method is used to indicate to the GSSManager that the 1951 application would like a particular provider to be used if no other 1952 provider can be found that supports the given mechanism. When a 1953 value of "null" is used instead of an Oid for the mechanism, the 1954 GSSManager must use the indicated provider for any mechanism. 1956 Calling this method repeatedly preserves the older settings, but 1957 raises them above newer ones in preference thus forming an ordered 1958 list of providers and Oid pairs that grows at the bottom. Thus, the 1959 older provider settings will be utilized first before this one is. 1961 If there are any previously existing preferences that conflict with 1962 the preference being set here, then the GSSManager should ignore this 1963 request. 1965 If the GSSManager implementation does not support an SPI with a 1966 pluggable provider architecture, it should throw a GSSException with 1967 the status code GSSException.UNAVAILABLE to indicate that the 1968 operation is unavailable. 1970 p The provider instance that should be used 1971 whenever support isneeded for mech. 1973 mech The mechanism for which the provider is being 1974 set. 1976 6.1.19. Example Code 1978 Suppose an application desired that when a mechanism of Oid m1 is 1979 needed, the system default providers always be checked first, and 1980 only when they do not support m1 should a provider A be checked. It 1981 would then make the call: 1983 1984 GSSManager mgr = GSSManager.getInstance(); 1986 mgr.addProviderAtEnd(A, m1); 1987 1989 Now, if it also desired that for all mechanisms the provider B be 1990 checked after all configured providers have been checked, it would 1991 then call: 1993 1994 mgr.addProviderAtEnd(B, null); 1995 1997 Effectively, the list of preferences now becomes {..., (A, m1), (B, 1998 null)}. 2000 Suppose, at a later time, the following call is made to the same 2001 GSSManager instance: 2003 2004 mgr.addProviderAtEnd(B, m2) 2005 2007 then the previous setting with the pair (B, null) subsumes this; 2008 therefore, this request should be ignored. The same would happen if 2009 a request is made for the already existing pairs of (A, m1) or (B, 2010 null). 2012 Please note, however, that the following call: 2014 2015 mgr.addProviderAtEnd(A, null) 2016 2018 is not subsumed by the previous setting of (A, m1) and the list will 2019 effectively become {..., (A, m1), (B, null), (A, null)}. 2021 6.2. public interface GSSName 2023 This interface encapsulates a single GSS-API principal entity. 2024 Different name formats and their definitions are identified with 2025 Universal Object Identifiers (Oids). The format of the names can be 2026 derived based on the unique oid of its namespace type. 2028 6.2.1. Example Code 2030 Included below are code examples utilizing the GSSName interface. 2031 The code below creates a GSSName, converts it to a mechanism name 2032 (MN), performs a comparison, obtains a printable representation of 2033 the name, exports it and then re-imports to obtain a new GSSName. 2035 2036 GSSManager mgr = GSSManager.getInstance(); 2038 // create a host-based service name 2039 GSSName name = mgr.createName("service@host", 2040 GSSName.NT_HOSTBASED_SERVICE); 2042 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 2044 GSSName mechName = name.canonicalize(krb5); 2046 // the above two steps are equivalent to the following 2047 GSSName mechName = mgr.createName("service@host", 2048 GSSName.NT_HOSTBASED_SERVICE, krb5); 2050 // perform name comparison 2051 if (name.equals(mechName)) 2052 print("Names are equals."); 2054 // obtain textual representation of name and its printable 2055 // name type 2056 print(mechName.toString() + 2057 mechName.getStringNameType().toString()); 2059 // export and re-import the name 2060 byte[] exportName = mechName.export(); 2062 // create a new name object from the exported buffer 2063 GSSName newName = mgr.createName(exportName, 2064 GSSName.NT_EXPORT_NAME); 2065 2067 6.2.2. Static Constants 2069 public static final Oid NT_HOSTBASED_SERVICE 2071 Oid indicating a host-based service name form. It is used to 2072 represent services associated with host computers. This name form is 2073 constructed using two elements, "service" and "hostname", as follows: 2075 service@hostname 2077 Values for the "service" element are registered with the IANA. It 2078 represents the following value: { iso(1) member-body(2) Unites 2079 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2080 service_name(4) } 2082 public static final Oid NT_USER_NAME 2084 Name type to indicate a named user on a local system. It represents 2085 the following value: { iso(1) member-body(2) United States(840) 2086 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2088 public static final Oid NT_MACHINE_UID_NAME 2090 Name type to indicate a numeric user identifier corresponding to a 2091 user on a local system (e.g., Uid). It represents the following 2092 value: { iso(1) member-body(2) United States(840) mit(113554) 2093 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2095 public static final Oid NT_STRING_UID_NAME 2097 Name type to indicate a string of digits representing the numeric 2098 user identifier of a user on a local system. It represents the 2099 following value: { iso(1) member-body(2) United States(840) 2100 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2102 public static final Oid NT_ANONYMOUS 2104 Name type for representing an anonymous entity. It represents the 2105 following value: { iso(1), org(3), dod(6), internet(1), security(5), 2106 nametypes(6), gss-anonymous-name(3) } 2108 public static final Oid NT_EXPORT_NAME 2110 Name type used to indicate an exported name produced by the export 2111 method. It represents the following value: { iso(1), org(3), dod(6), 2112 internet(1), security(5), nametypes(6), gss-api-exported-name(4) } 2114 6.2.3. equals 2116 public boolean equals(GSSName another) throws GSSException 2118 Compares two GSSName objects to determine whether they refer to the 2119 same entity. This method may throw a GSSException when the names 2120 cannot be compared. If either of the names represents an anonymous 2121 entity, the method will return "false". 2123 another GSSName object with which to compare. 2125 6.2.4. equals 2127 public boolean equals(Object another) 2129 A variation of the equals method, described in section 6.2.3, that is 2130 provided to override the Object.equals() method that the implementing 2131 class will inherit. The behavior is exactly the same as that in 2132 section 6.2.3 except that no GSSException is thrown; instead, "false" 2133 will be returned in the situation where an error occurs. (Note that 2134 the Java language specification requires that two objects that are 2135 equal according to the equals(Object) method must return the same 2136 integer result when the hashCode() method is called on them.) 2138 another GSSName object with which to compare. 2140 6.2.5. canonicalize 2142 public GSSName canonicalize(Oid mech) throws GSSException 2143 Creates a mechanism name (MN) from an arbitrary internal name. This 2144 is equivalent to using the factory methods described in sections 2145 6.1.8 or 6.1.9 that take the mechanism name as one of their 2146 parameters. 2148 mech The oid for the mechanism for which the canonical 2149 form of thename is requested. 2151 6.2.6. export 2153 public byte[] export() throws GSSException 2155 Returns a canonical contiguous byte representation of a mechanism 2156 name (MN), suitable for direct, byte-by-byte comparison by 2157 authorization functions. If the name is not an MN, implementations 2158 may throw a GSSException with the NAME_NOT_MN status code. If an 2159 implementation chooses not to throw an exception, it should use some 2160 system-specific default mechanism to canonicalize the name and then 2161 export it. The format of the header of the output buffer is 2162 specified in RFC 2743 [RFC2743]. 2164 6.2.7. toString 2166 public String toString() 2168 Returns a textual representation of the GSSName object. To retrieve 2169 the printed name format, which determines the syntax of the returned 2170 string, the getStringNameType method can be used. 2172 6.2.8. getStringNameType 2174 public Oid getStringNameType() throws GSSException 2176 Returns the oid representing the type of name returned through the 2177 toString method. Using this oid, the syntax of the printable name 2178 can be determined. 2180 6.2.9. isAnonymous 2182 public boolean isAnonymous() 2184 Tests if this name object represents an anonymous entity. Returns 2185 "true" if this is an anonymous name. 2187 6.2.10. isMN 2189 public boolean isMN() 2190 Tests if this name object contains only one mechanism element and is 2191 thus a mechanism name as defined by RFC 2743 [RFC2743]. 2193 6.3. public interface GSSCredential implements Cloneable 2195 This interface encapsulates the GSS-API credentials for an entity. A 2196 credential contains all the necessary cryptographic information to 2197 enable the creation of a context on behalf of the entity that it 2198 represents. It may contain multiple, distinct, mechanism-specific 2199 credential elements, each containing information for a specific 2200 security mechanism, but all referring to the same entity. 2202 A credential may be used to perform context initiation, acceptance, 2203 or both. 2205 GSS-API implementations must impose a local access-control policy on 2206 callers to prevent unauthorized callers from acquiring credentials to 2207 which they are not entitled. GSS-API credential creation is not 2208 intended to provide a "login to the network" function, as such a 2209 function would involve the creation of new credentials rather than 2210 merely acquiring a handle to existing credentials. Such functions, 2211 if required, should be defined in implementation-specific extensions 2212 to the API. 2214 If credential acquisition is time-consuming for a mechanism, the 2215 mechanism may choose to delay the actual acquisition until the 2216 credential is required (e.g., by GSSContext). Such mechanism- 2217 specific implementation decisions should be invisible to the calling 2218 application; thus, the query methods immediately following the 2219 creation of a credential object must return valid credential data, 2220 and may therefore incur the overhead of a deferred credential 2221 acquisition. 2223 Applications will create a credential object passing the desired 2224 parameters. The application can then use the query methods to obtain 2225 specific information about the instantiated credential object 2226 (equivalent to the gss_inquire routines). When the credential is no 2227 longer needed, the application should call the dispose (equivalent to 2228 gss_release_cred) method to release any resources held by the 2229 credential object and to destroy any cryptographically sensitive 2230 information. 2232 Classes implementing this interface also implement the Cloneable 2233 interface. This indicates that the class will support the clone() 2234 method that will allow the creation of duplicate credentials. This 2235 is useful when called just before the add() call to retain a copy of 2236 the original credential. 2238 6.3.1. Example Code 2240 This example code demonstrates the creation of a GSSCredential 2241 implementation for a specific entity, querying of its fields, and its 2242 release when it is no longer needed. 2244 2245 GSSManager mgr = GSSManager.getInstance(); 2247 // start by creating a name object for the entity 2248 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2250 // now acquire credentials for the entity 2251 GSSCredential cred = mgr.createCredential(name, 2252 GSSCredential.ACCEPT_ONLY); 2254 // display credential information - name, remaining lifetime, 2255 // and the mechanisms it has been acquired over 2256 print(cred.getName().toString()); 2257 print(cred.getRemainingLifetime()); 2259 Oid[] mechs = cred.getMechs(); 2260 if (mechs != null) { 2261 for (int i = 0; i < mechs.length; i++) 2262 print(mechs[i].toString()); 2263 } 2264 // release system resources held by the credential 2265 cred.dispose(); 2266 2268 6.3.2. Static Constants 2270 public static final int INITIATE_AND_ACCEPT 2272 Credential usage flag requesting that it be able to be used for both 2273 context initiation and acceptance. The value of this constant is 0. 2275 public static final int INITIATE_ONLY 2277 Credential usage flag requesting that it be able to be used for 2278 context initiation only. The value of this constant is 1. 2280 public static final int ACCEPT_ONLY 2282 Credential usage flag requesting that it be able to be used for 2283 context acceptance only. The value of this constant is 2. 2285 public static final int DEFAULT_LIFETIME 2286 A lifetime constant representing the default credential lifetime. 2287 The value of this constant is 0. 2289 public static final int INDEFINITE_LIFETIME 2291 A lifetime constant representing indefinite credential lifetime. The 2292 value of this constant is the maximum integer value in Java - 2293 Integer.MAX_VALUE. 2295 6.3.3. dispose 2297 public void dispose() throws GSSException 2299 Releases any sensitive information that the GSSCredential object may 2300 be containing. Applications should call this method as soon as the 2301 credential is no longer needed to minimize the time any sensitive 2302 information is maintained. 2304 6.3.4. getName 2306 public GSSName getName() throws GSSException 2308 Retrieves the name of the entity that the credential asserts. 2310 6.3.5. getName 2312 public GSSName getName(Oid mechOID) throws GSSException 2314 Retrieves a mechanism name of the entity that the credential asserts. 2315 Equivalent to calling canonicalize() on the name returned by section 2316 6.3.4. 2318 mechOID The mechanism for which information should be 2319 returned. 2321 6.3.6. getRemainingLifetime 2323 public int getRemainingLifetime() throws GSSException 2325 Returns the remaining lifetime in seconds for a credential. The 2326 remaining lifetime is the minimum lifetime for any of the underlying 2327 credential mechanisms. A return value of 2328 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2329 not expire. A return value of 0 indicates that the credential is 2330 already expired. 2332 6.3.7. getRemainingInitLifetime 2333 public int getRemainingInitLifetime(Oid mech) throws GSSException 2335 Returns the remaining lifetime in seconds for the credential to 2336 remain capable of initiating security contexts under the specified 2337 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2338 indicates that the credential does not expire for context initiation. 2339 A return value of 0 indicates that the credential is already expired. 2341 mechOID The mechanism for which information should be 2342 returned. 2344 6.3.8. getRemainingAcceptLifetime 2346 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2348 Returns the remaining lifetime in seconds for the credential to 2349 remain capable of accepting security contexts under the specified 2350 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2351 indicates that the credential does not expire for context acceptance. 2352 A return value of 0 indicates that the credential is already expired. 2354 mechOID The mechanism for which information should be 2355 returned. 2357 6.3.9. getUsage 2359 public int getUsage() throws GSSException 2361 Returns the credential usage flag as a union over all mechanisms. 2362 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2363 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2365 6.3.10. getUsage 2367 public int getUsage(Oid mechOID) throws GSSException 2369 Returns the credential usage flag for the specified mechanism only. 2370 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2371 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2373 mechOID The mechanism for which information should be 2374 returned. 2376 6.3.11. getMechs 2378 public Oid[] getMechs() throws GSSException 2380 Returns an array of mechanisms supported by this credential. 2382 6.3.12. add 2384 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2385 Oid mech, int usage) throws GSSException 2387 Adds a mechanism-specific credential-element to an existing 2388 credential. This method allows the construction of credentials one 2389 mechanism at a time. 2391 This routine is envisioned to be used mainly by context acceptors 2392 during the creation of acceptance credentials, which are to be used 2393 with a variety of clients using different security mechanisms. 2395 This routine adds the new credential element "in-place". To add the 2396 element in a new credential, first call clone() to obtain a copy of 2397 this credential, then call its add() method. 2399 aName Name of the principal for whom this credential is 2400 to beacquired. Use "null" to specify the default 2401 principal. 2403 initLifetime The number of seconds that credentials should 2404 remainvalid for initiating of security contexts. 2405 Use GSSCredential.INDEFINITE_LIFETIME to request 2406 that the credentials have the maximum permitted 2407 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 2408 request default credential lifetime. 2410 acceptLifetime The number of seconds that credentials 2411 shouldremain valid for accepting of security 2412 contexts. 2414 Use GSSCredential.INDEFINITE_LIFETIME to request 2415 that the credentials 2416 have the maximum permitted lifetime. Use 2417 GSSCredential.DEFAULT_LIFETIME to request default 2418 credential lifetime. 2420 mech The mechanisms over which the credential is to be 2421 acquired. 2423 usage The intended usage for this credential object. 2424 The value ofthis parameter must be one of: 2426 GSSCredential.INITIATE_AND_ACCEPT(0), 2427 GSSCredential.INITIATE_ONLY(1), or 2428 GSSCredential.ACCEPT_ONLY(2) 2430 6.3.13. equals 2432 public boolean equals(Object another) 2434 Tests if this GSSCredential refers to the same entity as the supplied 2435 object. The two credentials must be acquired over the same 2436 mechanisms and must refer to the same principal. Returns "true" if 2437 the two GSSCredentials refer to the same entity; "false" otherwise. 2438 (Note that the Java language specification [JLS] requires that two 2439 objects that are equal according to the equals(Object) method must 2440 return the same integer result when the hashCode() method is called 2441 on them.) 2443 another Another GSSCredential object for comparison. 2445 6.4. public interface GSSContext 2447 This interface encapsulates the GSS-API security context and provides 2448 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2449 available over the context. Security contexts are established 2450 between peers using locally acquired credentials. Multiple contexts 2451 may exist simultaneously between a pair of peers, using the same or 2452 different set of credentials. GSS-API functions in a manner 2453 independent of the underlying transport protocol and depends on its 2454 calling application to transport its tokens between peers. 2456 Before the context establishment phase is initiated, the context 2457 initiator may request specific characteristics desired of the 2458 established context. These can be set using the set methods. After 2459 the context is established, the caller can check the actual 2460 characteristic and services offered by the context using the query 2461 methods. 2463 The context establishment phase begins with the first call to the 2464 init method by the context initiator. During this phase, the 2465 initSecContext and acceptSecContext methods will produce GSS-API 2466 authentication tokens, which the calling application needs to send to 2467 its peer. If an error occurs at any point, an exception will get 2468 thrown and the code will start executing in a catch block where the 2469 exception may contain an output token that should be sent to the peer 2470 for debugging or informational purpose. If not, the normal flow of 2471 code continues and the application can make a call to the 2472 isEstablished() method. If this method returns "false" it indicates 2473 that a token is needed from its peer in order to continue the context 2474 establishment phase. A return value of "true" signals that the local 2475 end of the context is established. This may still require that a 2476 token be sent to the peer, if one is produced by GSS-API. During the 2477 context establishment phase, the isProtReady() method may be called 2478 to determine if the context can be used for the per-message 2479 operations. This allows applications to use per-message operations 2480 on contexts that aren't fully established. 2482 After the context has been established or the isProtReady() method 2483 returns "true", the query routines can be invoked to determine the 2484 actual characteristics and services of the established context. The 2485 application can also start using the per-message methods of wrap and 2486 getMIC to obtain cryptographic operations on application supplied 2487 data. 2489 When the context is no longer needed, the application should call 2490 dispose to release any system resources the context may be using. 2492 6.4.1. Example Code 2494 The example code presented below demonstrates the usage of the 2495 GSSContext interface for the initiating peer. Different operations 2496 on the GSSContext object are presented, including: object 2497 instantiation, setting of desired flags, context establishment, query 2498 of actual context flags, per-message operations on application data, 2499 and finally context deletion. 2501 2502 GSSManager mgr = GSSManager.getInstance(); 2504 // start by creating the name for a service entity 2505 GSSName targetName = mgr.createName("service@host", 2506 GSSName.NT_HOSTBASED_SERVICE); 2507 // create a context using default credentials for the above entity 2508 // and the implementation-specific default mechanism 2509 GSSContext context = mgr.createContext(targetName, 2510 null, /* default mechanism */ 2511 null, /* default credentials */ 2512 GSSContext.INDEFINITE_LIFETIME); 2514 // set desired context options - all others are "false" by default 2515 context.requestConf(true); 2516 context.requestMutualAuth(true); 2517 context.requestReplayDet(true); 2518 context.requestSequenceDet(true); 2519 // establish a context between peers - using byte arrays 2520 byte[]inTok = new byte[0]; 2522 try { 2523 do { 2524 byte[] outTok = context.initSecContext(inTok, 0, 2525 inTok.length); 2527 // send the token if present 2528 if (outTok != null) 2529 sendToken(outTok); 2531 // check if we should expect more tokens 2532 if (context.isEstablished()) 2533 break; 2535 // another token expected from peer 2536 inTok = readToken(); 2538 } while (true); 2540 } catch (GSSException e) { 2541 print("GSSAPI error: " + e.getMessage()); 2543 // If the exception contains an output token, 2544 // it should be sent to the acceptor. 2545 byte[] outTok = e.getOutputToken(); 2546 if (outTok != null) { 2547 sendToken(outTok); 2548 } 2550 return; 2551 } 2553 // display context information 2554 print("Remaining lifetime in seconds = " + context.getLifetime()); 2555 print("Context mechanism = " + context.getMech().toString()); 2556 print("Initiator = " + context.getSrcName().toString()); 2557 print("Acceptor = " + context.getTargName().toString()); 2559 if (context.getConfState()) 2560 print("Confidentiality security service available"); 2562 if (context.getIntegState()) 2563 print("Integrity security service available"); 2565 // perform wrap on an application-supplied message, appMsg, 2566 // using QOP = 0, and requesting privacy service 2567 byte[] appMsg ... 2569 MessageProp mProp = new MessageProp(0, true); 2571 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2573 if (mProp.getPrivacy()) 2574 print("Message protected with privacy."); 2576 sendToken(tok); 2578 // release the local end of the context 2579 context.dispose(); 2580 2582 6.4.2. Static Constants 2584 public static final int DEFAULT_LIFETIME 2586 A lifetime constant representing the default context lifetime. The 2587 value of this constant is 0. 2589 public static final int INDEFINITE_LIFETIME 2591 A lifetime constant representing indefinite context lifetime. The 2592 value of this constant is the maximum integer value in Java - 2593 Integer.MAX_VALUE. 2595 6.4.3. initSecContext 2597 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2598 throws GSSException 2600 Called by the context initiator to start the context creation 2601 process. This is equivalent to the stream-based method except that 2602 the token buffers are handled as byte arrays instead of using stream 2603 objects. This method may return an output token that the application 2604 will need to send to the peer for processing by the accept call. 2605 Typically, the application would do so by calling the flush() method 2606 on an OutputStream that encapsulates the connection between the two 2607 peers. The application can call isEstablished() to determine if the 2608 context establishment phase is complete for this peer. A return 2609 value of "false" from isEstablished() indicates that more tokens are 2610 expected to be supplied to the initSecContext() method. Note that it 2611 is possible that the initSecContext() method will return a token for 2612 the peer and isEstablished() will return "true" also. This indicates 2613 that the token needs to be sent to the peer, but the local end of the 2614 context is now fully established. 2616 Upon completion of the context establishment, the available context 2617 options may be queried through the get methods. 2619 A GSSException will be thrown if the call fails. Users should call 2620 its getOutputToken() method to find out if there is a token that can 2621 be sent to the acceptor to inform the reason for the error. 2623 inputBuf Token generated by the peer. This parameter is 2624 ignoredon the first call. 2626 offset The offset within the inputBuf where the token 2627 begins. 2629 len The length of the token within the inputBuf 2630 (starting at theoffset). 2632 6.4.4. Example Code 2634 2635 // Create a new GSSContext implementation object. 2636 // GSSContext wrapper implements interface GSSContext. 2637 GSSContext context = mgr.createContext(...); 2639 byte[] inTok = new byte[0]; 2641 try { 2642 do { 2643 byte[] outTok = context.initSecContext(inTok, 0, 2644 inTok.length); 2646 // send the token if present 2647 if (outTok != null) 2648 sendToken(outTok); 2650 // check if we should expect more tokens 2651 if (context.isEstablished()) 2652 break; 2654 // another token expected from peer 2655 inTok = readToken(); 2656 } while (true); 2658 } catch (GSSException e) { 2659 print("GSSAPI error: " + e.getMessage()); 2661 // If the exception contains an output token, 2662 // it should be sent to the acceptor. 2663 byte[] outTok = e.getOutputToken(); 2664 if (outTok != null) { 2665 sendToken(outTok); 2666 } 2667 } 2668 2670 6.4.5. initSecContext 2672 public int initSecContext(InputStream inStream, 2673 OutputStream outStream) throws GSSException 2675 Called by the context initiator to start the context creation 2676 process. This is equivalent to the byte-array-based method. This 2677 method may write an output token to the outStream, which the 2678 application will need to send to the peer for processing by the 2679 accept call. Typically, the application would do so by calling the 2680 flush() method on an OutputStream that encapsulates the connection 2681 between the two peers. The application can call isEstablished() to 2682 determine if the context establishment phase is complete for this 2683 peer. A return value of "false" from isEstablished indicates that 2684 more tokens are expected to be supplied to the initSecContext method. 2685 Note that it is possible that the initSecContext() method will return 2686 a token for the peer and isEstablished() will return "true" also. 2687 This indicates that the token needs to be sent to the peer, but the 2688 local end of the context is now fully established. 2690 The GSS-API authentication tokens contain a definitive start and end. 2691 This method will attempt to read one of these tokens per invocation, 2692 and may block on the stream if only part of the token is available. 2694 Upon completion of the context establishment, the available context 2695 options may be queried through the get methods. 2697 A GSSException will be thrown if the call fails. Users should call 2698 its getOutputToken() method to find out if there is a token that can 2699 be sent to the acceptor to inform the reason for the error. 2701 inStream Contains the token generated by the peer. This 2702 parameteris ignored on the first call. 2704 outStream Output stream where the output token will be 2705 written.During the final stage of context 2706 establishment, there may be no bytes written. 2708 6.4.6. Example Code 2710 This sample code merely demonstrates the token exchange during the 2711 context establishment phase. It is expected that most Java 2712 applications will use custom implementations of the Input and Output 2713 streams that encapsulate the communication routines. For instance, a 2714 simple read on the application InputStream, when called by the 2715 Context, might cause a token to be read from the peer, and a simple 2716 flush() on the application OutputStream might cause a previously 2717 written token to be transmitted to the peer. 2719 2720 // Create a new GSSContext implementation object. 2721 // GSSContext wrapper implements interface GSSContext. 2722 GSSContext context = mgr.createContext(...); 2723 // use standard java.io stream objects 2724 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2725 ByteArrayInputStream is = null; 2727 try { 2728 do { 2729 context.initSecContext(is, os); 2731 // send token if present 2732 if (os.size() > 0) 2733 sendToken(os); 2735 // check if we should expect more tokens 2736 if (context.isEstablished()) 2737 break; 2739 // another token expected from peer 2740 is = recvToken(); 2742 } while (true); 2744 } catch (GSSException e) { 2745 print("GSSAPI error: " + e.getMessage()); 2747 // If the exception contains an output token, 2748 // it should be sent to the acceptor. 2749 byte[] outTok = e.getOutputToken(); 2750 if (outTok != null) { 2751 sendToken(new ByteArrayOutputStream(outTok)); 2752 } 2753 } 2754 2756 6.4.7. acceptSecContext 2758 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2759 throws GSSException 2761 Called by the context acceptor upon receiving a token from the peer. 2762 This call is equivalent to the stream-based method except that the 2763 token buffers are handled as byte arrays instead of using stream 2764 objects. 2766 This method may return an output token that the application will need 2767 to send to the peer for further processing by the init call. 2769 The "null" return value indicates that no token needs to be sent to 2770 the peer. The application can call isEstablished() to determine if 2771 the context establishment phase is complete for this peer. A return 2772 value of "false" from isEstablished() indicates that more tokens are 2773 expected to be supplied to this method. 2775 Note that it is possible that acceptSecContext() will return a token 2776 for the peer and isEstablished() will return "true" also. This 2777 indicates that the token needs to be sent to the peer, but the local 2778 end of the context is now fully established. 2780 Upon completion of the context establishment, the available context 2781 options may be queried through the get methods. 2783 A GSSException will be thrown if the call fails. Users should call 2784 its getOutputToken() method to find out if there is a token that can 2785 be sent to the initiator to inform the reason for the error. 2787 inTok Token generated by the peer. 2789 offset The offset within the inTok where the token 2790 begins. 2792 len The length of the token within the inTok 2793 (starting at theoffset). 2795 6.4.8. Example Code 2797 2798 // acquire server credentials 2799 GSSCredential server = mgr.createCredential(...); 2801 // create acceptor GSS-API context from the default provider 2802 GSSContext context = mgr.createContext(server, null); 2804 try { 2805 do { 2806 byte[] inTok = readToken(); 2808 byte[] outTok = context.acceptSecContext(inTok, 0, 2809 inTok.length); 2811 // possibly send token to peer 2812 if (outTok != null) 2813 sendToken(outTok); 2815 // check if local context establishment is complete 2816 if (context.isEstablished()) 2817 break; 2818 } while (true); 2820 } catch (GSSException e) { 2821 print("GSS-API error: " + e.getMessage()); 2823 // If the exception contains an output token, 2824 // it should be sent to the initiator. 2825 byte[] outTok = e.getOutputToken(); 2826 if (outTok != null) { 2827 sendToken(outTok); 2828 } 2829 } 2830 2832 6.4.9. acceptSecContext 2834 public void acceptSecContext(InputStream inStream, 2835 OutputStream outStream) throws GSSException 2837 Called by the context acceptor upon receiving a token from the peer. 2838 This call is equivalent to the byte array method. It may write an 2839 output token to the outStream, which the application will need to 2840 send to the peer for processing by its initSecContext method. 2841 Typically, the application would do so by calling the flush() method 2842 on an OutputStream that encapsulates the connection between the two 2843 peers. The application can call isEstablished() to determine if the 2844 context establishment phase is complete for this peer. A return 2845 value of "false" from isEstablished() indicates that more tokens are 2846 expected to be supplied to this method. 2848 Note that it is possible that acceptSecContext() will return a token 2849 for the peer and isEstablished() will return "true" also. This 2850 indicates that the token needs to be sent to the peer, but the local 2851 end of the context is now fully established. 2853 The GSS-API authentication tokens contain a definitive start and end. 2854 This method will attempt to read one of these tokens per invocation, 2855 and may block on the stream if only part of the token is available. 2857 Upon completion of the context establishment, the available context 2858 options may be queried through the get methods. 2860 A GSSException will be thrown if the call fails. Users should call 2861 its getOutputToken() method to find out if there is a token that can 2862 be sent to the initiator to inform the reason for the error. 2864 inStream Contains the token generated by the peer. 2866 outStream Output stream where the output token will be 2867 written.During the final stage of context 2868 establishment, there may be no bytes written. 2870 6.4.10. Example Code 2872 This sample code merely demonstrates the token exchange during the 2873 context establishment phase. It is expected that most Java 2874 applications will use custom implementations of the Input and Output 2875 streams that encapsulate the communication routines. For instance, a 2876 simple read on the application InputStream, when called by the 2877 Context, might cause a token to be read from the peer, and a simple 2878 flush() on the application OutputStream might cause a previously 2879 written token to be transmitted to the peer. 2881 2882 // acquire server credentials 2883 GSSCredential server = mgr.createCredential(...); 2885 // create acceptor GSS-API context from the default provider 2886 GSSContext context = mgr.createContext(server, null); 2888 // use standard java.io stream objects 2889 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2890 ByteArrayInputStream is = null; 2892 try { 2893 do { 2895 is = recvToken(); 2897 context.acceptSecContext(is, os); 2899 // possibly send token to peer 2900 if (os.size() > 0) 2901 sendToken(os); 2903 // check if local context establishment is complete 2904 if (context.isEstablished()) 2905 break; 2906 } while (true); 2908 } catch (GSSException e) { 2909 print("GSS-API error: " + e.getMessage()); 2911 // If the exception contains an output token, 2912 // it should be sent to the initiator. 2913 byte[] outTok = e.getOutputToken(); 2914 if (outTok != null) { 2915 sendToken(new ByteArrayOutputStream(outTok)); 2916 } 2917 } 2918 2920 6.4.11. isEstablished 2922 public boolean isEstablished() 2924 Used during context establishment to determine the state of the 2925 context. Returns "true" if this is a fully established context on 2926 the caller's side and no more tokens are needed from the peer. 2927 Should be called after a call to initSecContext() or 2928 acceptSecContext() when no GSSException is thrown. 2930 6.4.12. dispose 2932 public void dispose() throws GSSException 2934 Releases any system resources and cryptographic information stored in 2935 the context object. This will invalidate the context. 2937 6.4.13. getWrapSizeLimit 2939 public int getWrapSizeLimit(int qop, boolean confReq, 2940 int maxTokenSize) throws GSSException 2942 Returns the maximum message size that, if presented to the wrap 2943 method with the same confReq and qop parameters, will result in an 2944 output token containing no more than the maxTokenSize bytes. 2946 This call is intended for use by applications that communicate over 2947 protocols that impose a maximum message size. It enables the 2948 application to fragment messages prior to applying protection. 2950 GSS-API implementations are recommended but not required to detect 2951 invalid QOP values when getWrapSizeLimit is called. This routine 2952 guarantees only a maximum message size, not the availability of 2953 specific QOP values for message protection. 2955 Successful completion of this call does not guarantee that wrap will 2956 be able to protect a message of the computed length, since this 2957 ability may depend on the availability of system resources at the 2958 time that wrap is called. However, if the implementation itself 2959 imposes an upper limit on the length of messages that may be 2960 processed by wrap, the implementation should not return a value that 2961 is greater than this length. 2963 qop Indicates the level of protection wrap will be 2964 asked toprovide. 2966 confReq Indicates if wrap will be asked to provide 2967 privacyservice. 2969 maxTokenSize The desired maximum size of the token emitted 2970 bywrap. 2972 6.4.14. wrap 2974 public byte[] wrap(byte[] inBuf, int offset, int len, 2975 MessageProp msgProp) throws GSSException 2977 Applies per-message security services over the established security 2978 context. The method will return a token with a cryptographic MIC and 2979 may optionally encrypt the specified inBuf. This method is 2980 equivalent in functionality to its stream counterpart. The returned 2981 byte array will contain both the MIC and the message. 2983 The MessageProp object is instantiated by the application and used to 2984 specify a QOP value that selects cryptographic algorithms, and a 2985 privacy service to optionally encrypt the message. The underlying 2986 mechanism that is used in the call may not be able to provide the 2987 privacy service. It sets the actual privacy service that it does 2988 provide in this MessageProp object, which the caller should then 2989 query upon return. If the mechanism is not able to provide the 2990 requested QOP, it throws a GSSException with the BAD_QOP code. 2992 Since some application-level protocols may wish to use tokens emitted 2993 by wrap to provide "secure framing", implementations should support 2994 the wrapping of zero-length messages. 2996 The application will be responsible for sending the token to the 2997 peer. 2999 inBuf Application data to be protected. 3001 offset The offset within the inBuf where the data 3002 begins. 3004 len The length of the data within the inBuf (starting 3005 at theoffset). 3007 msgProp Instance of MessageProp that is used by the 3008 application toset the desired QOP and privacy 3009 state. Set the desired QOP to 0 to request the 3010 default QOP. Upon return from this method, this 3011 object will contain the actual privacy state that 3012 was applied to the message by the underlying 3013 mechanism. 3015 6.4.15. wrap 3017 public void wrap(InputStream inStream, OutputStream outStream, 3018 MessageProp msgProp) throws GSSException 3020 Allows to apply per-message security services over the established 3021 security context. The method will produce a token with a 3022 cryptographic MIC and may optionally encrypt the message in inStream. 3023 The outStream will contain both the MIC and the message. 3025 The MessageProp object is instantiated by the application and used to 3026 specify a QOP value that selects cryptographic algorithms, and a 3027 privacy service to optionally encrypt the message. The underlying 3028 mechanism that is used in the call may not be able to provide the 3029 privacy service. It sets the actual privacy service that it does 3030 provide in this MessageProp object, which the caller should then 3031 query upon return. If the mechanism is not able to provide the 3032 requested QOP, it throws a GSSException with the BAD_QOP code. 3034 Since some application-level protocols may wish to use tokens emitted 3035 by wrap to provide "secure framing", implementations should support 3036 the wrapping of zero-length messages. 3038 The application will be responsible for sending the token to the 3039 peer. 3041 inStream Input stream containing the application data to 3042 beprotected. 3044 outStream The output stream to which to write the protected 3045 message.The application is responsible for 3046 sending this to the other peer for processing in 3047 its unwrap method. 3049 msgProp Instance of MessageProp that is used by the 3050 application toset the desired QOP and privacy 3051 state. Set the desired QOP to 0 to request the 3052 default QOP. Upon return from this method, this 3053 object will contain the actual privacy state that 3054 was applied to the message by the underlying 3055 mechanism. 3057 6.4.16. unwrap 3059 public byte[] unwrap(byte[] inBuf, int offset, int len, 3060 MessageProp msgProp) throws GSSException 3062 Used by the peer application to process tokens generated with the 3063 wrap call. This call is equal in functionality to its stream 3064 counterpart. The method will return the message supplied in the peer 3065 application to the wrap call, verifying the embedded MIC. 3067 The MessageProp object is instantiated by the application and is used 3068 by the underlying mechanism to return information to the caller such 3069 as the QOP, whether confidentiality was applied to the message, and 3070 other supplementary message state information. 3072 Since some application-level protocols may wish to use tokens emitted 3073 by wrap to provide "secure framing", implementations should support 3074 the wrapping and unwrapping of zero-length messages. 3076 inBuf GSS-API wrap token received from peer. 3078 offset The offset within the inBuf where the token 3079 begins. 3081 len The length of the token within the inBuf 3082 (starting at theoffset). 3084 msgProp Upon return from the method, this object will 3085 contain theapplied QOP, the privacy state of the 3086 message, and supplementary information, described 3087 in section 4.12.3, stating whether the token was 3088 a duplicate, old, out of sequence, or arriving 3089 after a gap. 3091 6.4.17. unwrap 3093 public void unwrap(InputStream inStream, OutputStream outStream, 3094 MessageProp msgProp) throws GSSException 3096 Used by the peer application to process tokens generated with the 3097 wrap call. This call is equal in functionality to its byte array 3098 counterpart. It will produce the message supplied in the peer 3099 application to the wrap call, verifying the embedded MIC. 3101 The MessageProp object is instantiated by the application and is used 3102 by the underlying mechanism to return information to the caller such 3103 as the QOP, whether confidentiality was applied to the message, and 3104 other supplementary message state information. 3106 Since some application-level protocols may wish to use tokens emitted 3107 by wrap to provide "secure framing", implementations should support 3108 the wrapping and unwrapping of zero-length messages. 3110 inStream Input stream containing the GSS-API wrap token 3111 receivedfrom the peer. 3113 outStream The output stream to which to write the 3114 application message. 3116 msgProp Upon return from the method, this object will 3117 contain theapplied QOP, the privacy state of the 3118 message, and supplementary information, described 3119 in section 4.12.3, stating whether the token was 3120 a duplicate, old, out of sequence, or arriving 3121 after a gap. 3123 6.4.18. getMIC 3125 public byte[] getMIC(byte[] inMsg, int offset, int len, 3126 MessageProp msgProp) throws GSSException 3128 Returns a token containing a cryptographic MIC for the supplied 3129 message for transfer to the peer application. Unlike wrap, which 3130 encapsulates the user message in the returned token, only the message 3131 MIC is returned in the output token. This method is identical in 3132 functionality to its stream counterpart. 3134 Note that privacy can only be applied through the wrap call. 3136 Since some application-level protocols may wish to use tokens emitted 3137 by getMIC to provide "secure framing", implementations should support 3138 derivation of MICs from zero-length messages. 3140 inMsg Message over which to generate MIC. 3142 offset The offset within the inMsg where the token 3143 begins. 3145 len The length of the token within the inMsg 3146 (starting at theoffset). 3148 msgProp Instance of MessageProp that is used by the 3149 application toset the desired QOP. Set the 3150 desired QOP to 0 in msgProp to request the 3151 default QOP. Alternatively, pass in "null" for 3152 msgProp to request default QOP. 3154 6.4.19. getMIC 3156 public void getMIC(InputStream inStream, OutputStream outStream, 3157 MessageProp msgProp) throws GSSException 3159 Produces a token containing a cryptographic MIC for the supplied 3160 message, for transfer to the peer application. Unlike wrap, which 3161 encapsulates the user message in the returned token, only the message 3162 MIC is produced in the output token. This method is identical in 3163 functionality to its byte array counterpart. 3165 Note that privacy can only be applied through the wrap call. 3167 Since some application-level protocols may wish to use tokens emitted 3168 by getMIC to provide "secure framing", implementations should support 3169 derivation of MICs from zero-length messages. 3171 inStream Input stream containing the message over which to 3172 generate MIC. 3174 outStream Output stream to which to write the GSS-API 3175 output token. 3177 msgProp Instance of MessageProp that is used by the 3178 application toset the desired QOP. Set the 3179 desired QOP to 0 in msgProp to request the 3180 default QOP. Alternatively, pass in "null" for 3181 msgProp to request default QOP. 3183 6.4.20. verifyMIC 3185 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 3186 byte[] inMsg, int msgOffset, int msgLen, 3187 MessageProp msgProp) throws GSSException 3189 Verifies the cryptographic MIC, contained in the token parameter, 3190 over the supplied message. This method is equivalent in 3191 functionality to its stream counterpart. 3193 The MessageProp object is instantiated by the application and is used 3194 by the underlying mechanism to return information to the caller such 3195 as the QOP indicating the strength of protection that was applied to 3196 the message and other supplementary message state information. 3198 Since some application-level protocols may wish to use tokens emitted 3199 by getMIC to provide "secure framing", implementations should support 3200 the calculation and verification of MICs over zero-length messages. 3202 inTok Token generated by peer's getMIC method. 3204 tokOffset The offset within the inTok where the token 3205 begins. 3207 tokLen The length of the token within the inTok 3208 (starting at theoffset). 3210 inMsg Application message over which to verify the 3211 cryptographic MIC. 3213 msgOffset The offset within the inMsg where the message 3214 begins. 3216 msgLen The length of the message within the inMsg 3217 (starting at theoffset). 3219 msgProp Upon return from the method, this object will 3220 contain theapplied QOP and supplementary 3221 information, described in section 4.12.3, stating 3222 whether the token was a duplicate, old, out of 3223 sequence, or arriving after a gap. The 3224 confidentiality state will be set to "false". 3226 6.4.21. verifyMIC 3228 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3229 MessageProp msgProp) throws GSSException 3231 Verifies the cryptographic MIC, contained in the token parameter, 3232 over the supplied message. This method is equivalent in 3233 functionality to its byte array counterpart. 3235 The MessageProp object is instantiated by the application and is used 3236 by the underlying mechanism to return information to the caller such 3237 as the QOP indicating the strength of protection that was applied to 3238 the message and other supplementary message state information. 3240 Since some application-level protocols may wish to use tokens emitted 3241 by getMIC to provide "secure framing", implementations should support 3242 the calculation and verification of MICs over zero-length messages. 3244 tokStream Input stream containing the token generated by 3245 the peer'sgetMIC method. 3247 msgStream Input stream containing the application message 3248 over which toverify the cryptographic MIC. 3250 msgProp Upon return from the method, this object will 3251 contain theapplied QOP and supplementary 3252 information, described in section 4.12.3, stating 3253 whether the token was a duplicate, old, out of 3254 sequence, or arriving after a gap. The 3255 confidentiality state will be set to "false". 3257 6.4.22. export 3259 public byte[] export() throws GSSException 3261 Provided to support the sharing of work between multiple processes. 3262 This routine will typically be used by the context acceptor, in an 3263 application where a single process receives incoming connection 3264 requests and accepts security contexts over them, then passes the 3265 established context to one or more other processes for message 3266 exchange. 3268 This method deactivates the security context and creates an inter- 3269 process token which, when passed to the byte array constructor of the 3270 GSSContext interface in another process, will re-activate the context 3271 in the second process. Only a single instantiation of a given 3272 context may be active at any one time; a subsequent attempt by a 3273 context exporter to access the exported security context will fail. 3275 The implementation may constrain the set of processes by which the 3276 inter-process token may be imported, either as a function of local 3277 security policy, or as a result of implementation decisions. For 3278 example, some implementations may constrain contexts to be passed 3279 only between processes that run under the same account, or which are 3280 part of the same process group. 3282 The inter-process token may contain security-sensitive information 3283 (for example, cryptographic keys). While mechanisms are encouraged 3284 to either avoid placing such sensitive information within inter- 3285 process tokens or to encrypt the token before returning it to the 3286 application, in a typical GSS-API implementation, this may not be 3287 possible. Thus, the application must take care to protect the inter- 3288 process token, and ensure that any process to which the token is 3289 transferred is trustworthy. 3291 6.4.23. requestMutualAuth 3293 public void requestMutualAuth(boolean state) throws GSSException 3295 Sets the request state of the mutual authentication flag for the 3296 context. This method is only valid before the context creation 3297 process begins and only for the initiator. 3299 state Boolean representing if mutual authentication 3300 should berequested during context establishment. 3302 6.4.24. requestReplayDet 3304 public void requestReplayDet(boolean state) throws GSSException 3306 Sets the request state of the replay detection service for the 3307 context. This method is only valid before the context creation 3308 process begins and only for the initiator. 3310 state Boolean representing if replay detection is 3311 desired over theestablished context. 3313 6.4.25. requestSequenceDet 3315 public void requestSequenceDet(boolean state) throws GSSException 3317 Sets the request state for the sequence checking service of the 3318 context. This method is only valid before the context creation 3319 process begins and only for the initiator. 3321 state Boolean representing if sequence detection is 3322 desired overthe established context. 3324 6.4.26. requestCredDeleg 3326 public void requestCredDeleg(boolean state) throws GSSException 3328 Sets the request state for the credential delegation flag for the 3329 context. This method is only valid before the context creation 3330 process begins and only for the initiator. 3332 state Boolean representing if credential delegation is 3333 desired. 3335 6.4.27. requestAnonymity 3337 public void requestAnonymity(boolean state) throws GSSException 3339 Requests anonymous support over the context. This method is only 3340 valid before the context creation process begins and only for the 3341 initiator. 3343 state Boolean representing if anonymity support is 3344 requested. 3346 6.4.28. requestConf 3348 public void requestConf(boolean state) throws GSSException 3350 Requests that confidentiality service be available over the context. 3351 This method is only valid before the context creation process begins 3352 and only for the initiator. 3354 state Boolean indicating if confidentiality services 3355 are to berequested for the context. 3357 6.4.29. requestInteg 3359 public void requestInteg(boolean state) throws GSSException 3361 Requests that integrity services be available over the context. This 3362 method is only valid before the context creation process begins and 3363 only for the initiator. 3365 state Boolean indicating if integrity services are to 3366 be requestedfor the context. 3368 6.4.30. requestLifetime 3370 public void requestLifetime(int lifetime) throws GSSException 3371 Sets the desired lifetime for the context in seconds. This method is 3372 only valid before the context creation process begins and only for 3373 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 3374 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 3375 lifetime. 3377 lifetime The desired context lifetime in seconds. 3379 6.4.31. setChannelBinding 3381 public void setChannelBinding(ChannelBinding cb) throws GSSException 3383 Sets the channel bindings to be used during context establishment. 3384 This method is only valid before the context creation process begins. 3386 cb Channel bindings to be used. 3388 6.4.32. getCredDelegState 3390 public boolean getCredDelegState() 3392 Returns the state of the delegated credentials for the context. When 3393 issued before context establishment is completed or when the 3394 isProtReady method returns "false", it returns the desired state; 3395 otherwise, it will indicate the actual state over the established 3396 context. 3398 6.4.33. getMutualAuthState 3400 public boolean getMutualAuthState() 3402 Returns the state of the mutual authentication option for the 3403 context. When issued before context establishment completes or when 3404 the isProtReady method returns "false", it returns the desired state; 3405 otherwise, it will indicate the actual state over the established 3406 context. 3408 6.4.34. getReplayDetState 3410 public boolean getReplayDetState() 3412 Returns the state of the replay detection option for the context. 3413 When issued before context establishment completes or when the 3414 isProtReady method returns "false", it returns the desired state; 3415 otherwise, it will indicate the actual state over the established 3416 context. 3418 6.4.35. getSequenceDetState 3420 public boolean getSequenceDetState() 3422 Returns the state of the sequence detection option for the context. 3423 When issued before context establishment completes or when the 3424 isProtReady method returns "false", it returns the desired state; 3425 otherwise, it will indicate the actual state over the established 3426 context. 3428 6.4.36. getAnonymityState 3430 public boolean getAnonymityState() 3432 Returns "true" if this is an anonymous context. When issued before 3433 context establishment completes or when the isProtReady method 3434 returns "false", it returns the desired state; otherwise, it will 3435 indicate the actual state over the established context. 3437 6.4.37. isTransferable 3439 public boolean isTransferable() throws GSSException 3441 Returns "true" if the context is transferable to other processes 3442 through the use of the export method. This call is only valid on 3443 fully established contexts. 3445 6.4.38. isProtReady 3447 public boolean isProtReady() 3449 Returns "true" if the per-message operations can be applied over the 3450 context. Some mechanisms may allow the usage of per-message 3451 operations before the context is fully established. This will also 3452 indicate that the get methods will return actual context state 3453 characteristics instead of the desired ones. 3455 6.4.39. getConfState 3457 public boolean getConfState() 3459 Returns the confidentiality service state over the context. When 3460 issued before context establishment completes or when the isProtReady 3461 method returns "false", it returns the desired state; otherwise, it 3462 will indicate the actual state over the established context. 3464 6.4.40. getIntegState 3465 public boolean getIntegState() 3467 Returns the integrity service state over the context. When issued 3468 before context establishment completes or when the isProtReady method 3469 returns "false", it returns the desired state; otherwise, it will 3470 indicate the actual state over the established context. 3472 6.4.41. getLifetime 3474 public int getLifetime() 3476 Returns the context lifetime in seconds. When issued before context 3477 establishment completes or when the isProtReady method returns 3478 "false", it returns the desired lifetime; otherwise, it will indicate 3479 the remaining lifetime for the context. 3481 6.4.42. getSrcName 3483 public GSSName getSrcName() throws GSSException 3485 Returns the name of the context initiator. This call is valid only 3486 after the context is fully established or the isProtReady method 3487 returns "true". It is guaranteed to return an MN. 3489 6.4.43. getTargName 3491 public GSSName getTargName() throws GSSException 3493 Returns the name of the context target (acceptor). This call is 3494 valid only after the context is fully established or the isProtReady 3495 method returns "true". It is guaranteed to return an MN. 3497 6.4.44. getMech 3499 public Oid getMech() throws GSSException 3501 Returns the mechanism oid for this context. This method may be 3502 called before the context is fully established, but the mechanism 3503 returned may change on successive calls in negotiated mechanism case. 3505 6.4.45. getDelegCred 3507 public GSSCredential getDelegCred() throws GSSException 3509 Returns the delegated credential object on the acceptor's side. To 3510 check for availability of delegated credentials call 3511 getDelegCredState. This call is only valid on fully established 3512 contexts. 3514 6.4.46. isInitiator 3516 public boolean isInitiator() throws GSSException 3518 Returns "true" if this is the initiator of the context. This call is 3519 only valid after the context creation process has started. 3521 6.5. public class MessageProp 3523 This is a utility class used within the per-message GSSContext 3524 methods to convey per-message properties. 3526 When used with the GSSContext interface's wrap and getMIC methods, an 3527 instance of this class is used to indicate the desired QOP and to 3528 request if confidentiality services are to be applied to caller 3529 supplied data (wrap only). To request default QOP, the value of 0 3530 should be used for QOP. 3532 When used with the unwrap and verifyMIC methods of the GSSContext 3533 interface, an instance of this class will be used to indicate the 3534 applied QOP and confidentiality services over the supplied message. 3535 In the case of verifyMIC, the confidentiality state will always be 3536 "false". Upon return from these methods, this object will also 3537 contain any supplementary status values applicable to the processed 3538 token. The supplementary status values can indicate old tokens, out 3539 of sequence tokens, gap tokens, or duplicate tokens. 3541 6.5.1. Constructors 3543 public MessageProp(boolean privState) 3545 Constructor that sets QOP to 0 indicating that the default QOP is 3546 requested. 3548 privState The desired privacy state. "true" for privacy 3549 and"false" for integrity only. 3551 public MessageProp(int qop, boolean privState) 3553 Constructor that sets the values for the qop and privacy state. 3555 qop The desired QOP. Use 0 to request a default QOP. 3557 privState The desired privacy state. "true" for privacy 3558 and"false" for integrity only. 3560 6.5.2. getQOP 3561 public int getQOP() 3563 Retrieves the QOP value. 3565 6.5.3. getPrivacy 3567 public boolean getPrivacy() 3569 Retrieves the privacy state. 3571 6.5.4. getMinorStatus 3573 public int getMinorStatus() 3575 Retrieves the minor status that the underlying mechanism might have 3576 set. 3578 6.5.5. getMinorString 3580 public String getMinorString() 3582 Returns a string explaining the mechanism-specific error code. "null" 3583 will be returned when no mechanism error code has been set. 3585 6.5.6. setQOP 3587 public void setQOP(int qopVal) 3589 Sets the QOP value. 3591 qopVal The QOP value to be set. Use 0 to request a 3592 default QOPvalue. 3594 6.5.7. setPrivacy 3596 public void setPrivacy(boolean privState) 3598 Sets the privacy state. 3600 privState The privacy state to set. 3602 6.5.8. isDuplicateToken 3604 public boolean isDuplicateToken() 3606 Returns "true" if this is a duplicate of an earlier token. 3608 6.5.9. isOldToken 3610 public boolean isOldToken() 3612 Returns "true" if the token's validity period has expired. 3614 6.5.10. isUnseqToken 3616 public boolean isUnseqToken() 3618 Returns "true" if a later token has already been processed. 3620 6.5.11. isGapToken 3622 public boolean isGapToken() 3624 Returns "true" if an expected per-message token was not received. 3626 6.5.12. setSupplementaryStates 3628 public void setSupplementaryStates(boolean duplicate, 3629 boolean old, boolean unseq, boolean gap, 3630 int minorStatus, String minorString) 3632 This method sets the state for the supplementary information flags 3633 and the minor status in MessageProp. It is not used by the 3634 application but by the GSS implementation to return this information 3635 to the caller of a per-message context method. 3637 duplicate "true" if the token was a duplicate of an earlier 3638 token; otherwise,"false". 3640 old "true" if the token's validity period has 3641 expired; otherwise, "false". 3643 unseq "true" if a later token has already been 3644 processed; otherwise, "false". 3646 gap "true" if one or more predecessor tokens have not 3647 yet beensuccessfully processed; otherwise, 3648 "false". 3650 minorStatus The integer minor status code that the 3651 underlyingmechanism wants to set. 3653 minorString The textual representation of the minorStatus 3654 value. 3656 6.6. public class ChannelBinding 3658 The GSS-API accommodates the concept of caller-provided channel 3659 binding information. Channel bindings are used to strengthen the 3660 quality with which peer entity authentication is provided during 3661 context establishment. They enable the GSS-API callers to bind the 3662 establishment of the security context to relevant characteristics 3663 like addresses or to application-specific data. 3665 The caller initiating the security context must determine the 3666 appropriate channel binding values to set in the GSSContext object. 3667 The acceptor must provide an identical binding in order to validate 3668 that received tokens possess correct channel-related characteristics. 3670 Use of channel bindings is optional in GSS-API. Since channel- 3671 binding information may be transmitted in context establishment 3672 tokens, applications should therefore not use confidential data as 3673 channel-binding components. 3675 6.6.1. Constructors 3677 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3678 byte[] appData) 3680 Create a ChannelBinding object with user-supplied address information 3681 and data. "null" values can be used for any fields that the 3682 application does not want to specify. 3684 initAddr The address of the context initiator. "null" 3685 value can besupplied to indicate that the 3686 application does not want to set this value. 3688 acceptAddr The address of the context acceptor. "null" value 3689 canbe supplied to indicate that the application 3690 does not want to set this value. 3692 appData Application-supplied data to be used as part of 3693 thechannel bindings. "null" value can be supplied 3694 to indicate that the application does not want to 3695 set this value. 3697 public ChannelBinding(byte[] appData) 3699 Creates a ChannelBinding object without any addressing information. 3701 appData Application supplied data to be used as part of 3702 thechannel bindings. 3704 6.6.2. getInitiatorAddress 3706 public InetAddress getInitiatorAddress() 3708 Returns the initiator's address for this channel binding. "null" is 3709 returned if the address has not been set. 3711 6.6.3. getAcceptorAddress 3713 public InetAddress getAcceptorAddress() 3715 Returns the acceptor's address for this channel binding. "null" is 3716 returned if the address has not been set. 3718 6.6.4. getApplicationData 3720 public byte[] getApplicationData() 3722 Returns application data being used as part of the ChannelBinding. 3723 "null" is returned if no application data has been specified for the 3724 channel binding. 3726 6.6.5. equals 3728 public boolean equals(Object obj) 3730 Returns "true" if two channel bindings match. (Note that the Java 3731 language specification requires that two objects that are equal 3732 according to the equals(Object) method must return the same integer 3733 result when the hashCode() method is called on them.) 3735 obj Another channel binding with which to compare. 3737 6.7. public class Oid 3739 This class represents Universal Object Identifiers (Oids) and their 3740 associated operations. 3742 Oids are hierarchically globally interpretable identifiers used 3743 within the GSS-API framework to identify mechanisms and name formats. 3745 The structure and encoding of Oids is defined in ISOIEC-8824 and 3746 ISOIEC-8825. For example, the Oid representation of the Kerberos v5 3747 mechanism is "1.2.840.113554.1.2.2". 3749 The GSSName name class contains public static Oid objects 3750 representing the standard name types defined in GSS-API. 3752 6.7.1. Constructors 3754 public Oid(String strOid) throws GSSException 3756 Creates an Oid object from a string representation of its integer 3757 components (e.g., "1.2.840.113554.1.2.2"). 3759 strOid The string representation for the oid. 3761 public Oid(InputStream derOid) throws GSSException 3763 Creates an Oid object from its DER encoding. This refers to the full 3764 encoding including tag and length. The structure and encoding of 3765 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3766 identical in functionality to its byte array counterpart. 3768 derOid Stream containing the DER-encoded oid. 3770 public Oid(byte[] DEROid) throws GSSException 3772 Creates an Oid object from its DER encoding. This refers to the full 3773 encoding including tag and length. The structure and encoding of 3774 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3775 identical in functionality to its byte array counterpart. 3777 derOid Byte array storing a DER-encoded oid. 3779 6.7.2. toString 3781 public String toString() 3783 Returns a string representation of the oid's integer components in 3784 dot separated notation (e.g., "1.2.840.113554.1.2.2"). 3786 6.7.3. equals 3788 public boolean equals(Object Obj) 3790 Returns "true" if the two Oid objects represent the same oid value. 3791 (Note that the Java language specification [JLS] requires that two 3792 objects that are equal according to the equals(Object) method must 3793 return the same integer result when the hashCode() method is called 3794 on them.) 3796 obj Another Oid object with which to compare. 3798 6.7.4. getDER 3799 public byte[] getDER() 3801 Returns the full ASN.1 DER encoding for this oid object, which 3802 includes the tag and length. 3804 6.7.5. containedIn 3806 public boolean containedIn(Oid[] oids) 3808 A utility method to test if an Oid object is contained within the 3809 supplied Oid object array. 3811 oids An array of oids to search. 3813 6.8. public class GSSException extends Exception 3815 This exception is thrown whenever a fatal GSS-API error occurs 3816 including mechanism-specific errors. It may contain both, the major 3817 and minor, GSS-API status codes. The mechanism implementors are 3818 responsible for setting appropriate minor status codes when throwing 3819 this exception. Aside from delivering the numeric error code(s) to 3820 the caller, this class performs the mapping from their numeric values 3821 to textual representations. This exception may also include an 3822 output token that should be sent to the peer. For example, when an 3823 initSecContext call fails due to a fatal error, the mechanism may 3824 define an error token that should be sent to the peer for debugging 3825 or informational purpose. All Java GSS-API methods are declared 3826 throwing this exception. 3828 All implementations are encouraged to use the Java 3829 internationalization techniques to provide local translations of the 3830 message strings. 3832 6.8.1. Static Constants 3834 All valid major GSS-API error code values are declared as constants 3835 in this class. 3837 public static final int BAD_BINDINGS 3839 Channel bindings mismatch error. The value of this constant is 1. 3841 public static final int BAD_MECH 3843 Unsupported mechanism requested error. The value of this constant is 3844 2. 3846 public static final int BAD_NAME 3847 Invalid name provided error. The value of this constant is 3. 3849 public static final int BAD_NAMETYPE 3851 Name of unsupported type provided error. The value of this constant 3852 is 4. 3854 public static final int BAD_STATUS 3856 Invalid status code error - this is the default status value. The 3857 value of this constant is 5. 3859 public static final int BAD_MIC 3861 Token had invalid integrity check error. The value of this constant 3862 is 6. 3864 public static final int CONTEXT_EXPIRED 3866 Specified security context expired error. The value of this constant 3867 is 7. 3869 public static final int CREDENTIALS_EXPIRED 3871 Expired credentials detected error. The value of this constant is 8. 3873 public static final int DEFECTIVE_CREDENTIAL 3875 Defective credential error. The value of this constant is 9. 3877 public static final int DEFECTIVE_TOKEN 3879 Defective token error. The value of this constant is 10. 3881 public static final int FAILURE 3883 General failure, unspecified at GSS-API level. The value of this 3884 constant is 11. 3886 public static final int NO_CONTEXT 3888 Invalid security context error. The value of this constant is 12. 3890 public static final int NO_CRED 3892 Invalid credentials error. The value of this constant is 13. 3894 public static final int BAD_QOP 3895 Unsupported QOP value error. The value of this constant is 14. 3897 public static final int UNAUTHORIZED 3899 Operation unauthorized error. The value of this constant is 15. 3901 public static final int UNAVAILABLE 3903 Operation unavailable error. The value of this constant is 16. 3905 public static final int DUPLICATE_ELEMENT 3907 Duplicate credential element requested error. The value of this 3908 constant is 17. 3910 public static final int NAME_NOT_MN 3912 Name contains multi-mechanism elements error. The value of this 3913 constant is 18. 3915 public static final int DUPLICATE_TOKEN 3917 The token was a duplicate of an earlier token. This is contained in 3918 an exception only when detected during context establishment, in 3919 which case it is considered a fatal error. (Non-fatal supplementary 3920 codes are indicated via the MessageProp object.) The value of this 3921 constant is 19. 3923 public static final int OLD_TOKEN 3925 The token's validity period has expired. This is contained in an 3926 exception only when detected during context establishment, in which 3927 case it is considered a fatal error. (Non-fatal supplementary codes 3928 are indicated via the MessageProp object.) The value of this 3929 constant is 20. 3931 public static final int UNSEQ_TOKEN 3933 A later token has already been processed. This is contained in an 3934 exception only when detected during context establishment, in which 3935 case it is considered a fatal error. (Non-fatal supplementary codes 3936 are indicated via the MessageProp object.) The value of this 3937 constant is 21. 3939 public static final int GAP_TOKEN 3941 An expected per-message token was not received. This is contained in 3942 an exception only when detected during context establishment, in 3943 which case it is considered a fatal error. (Non-fatal supplementary 3944 codes are indicated via the MessageProp object.) The value of this 3945 constant is 22. 3947 6.8.2. Constructors 3949 public GSSException(int majorCode) 3951 Creates a GSSException object with a specified major code. 3953 Calling this constructor is equivalent to calling 3954 GSSException(majorCode, 0, null, null). 3956 public GSSException(int majorCode, int minorCode, String minorString) 3958 Creates a GSSException object with the specified major code, minor 3959 code, and minor code textual explanation. This constructor is to be 3960 used when the exception is originating from the security mechanism. 3961 It allows to specify the GSS code and the mechanism code. 3963 Calling this constructor is equivalent to calling 3964 GSSException(majorCode, minorCode, minorString, null). 3966 public GSSException(int majorCode, String majorString, 3968 int minorCode, String minorString, byte[] outputToken) 3970 Creates a GSSException object with the specified major code, major 3971 code textual explanation, minor code, minor code textual explanation, 3972 and an output token. This is a general-purpose constructor that can 3973 be used to create any type of GSSException. 3975 majorCode The GSS error code causing this exception to be 3976 thrown. 3978 majorString The textual explanation of the GSS error code. 3979 If null isprovided, a default explanation that 3980 matches the majorCode will be set. 3982 minorCode The mechanism error code causing this exception 3983 to bethrown. Can be 0 if no mechanism error code 3984 is available. 3986 minorString The textual explanation of the mechanism error 3987 code.Can be null if no textual explanation is 3988 available. 3990 outputToken The output token that should be sent to the 3991 peer.Can be null if no such token is available. 3992 It must not be an empty array. When provided, 3993 the array will be cloned to protect against 3994 subsequent modifications. 3996 6.8.3. getMajor 3998 public int getMajor() 4000 Returns the major code representing the GSS error code that caused 4001 this exception to be thrown. 4003 6.8.4. getMinor 4005 public int getMinor() 4007 Returns the mechanism error code that caused this exception. The 4008 minor code is set by the underlying mechanism. Value of 0 indicates 4009 that mechanism error code is not set. 4011 6.8.5. getMajorString 4013 public String getMajorString() 4015 Returns a string explaining the GSS major error code causing this 4016 exception to be thrown. 4018 6.8.6. getMinorString 4020 public String getMinorString() 4022 Returns a string explaining the mechanism-specific error code. "null" 4023 will be returned when no string explaining the mechanism error code 4024 has been set. 4026 6.8.7. getOutputToken 4028 public byte[] getOutputToken 4030 Returns the output token in a new byte array. 4032 If the method (For example, GSSContext#initSecContext) that throws 4033 this GSSException needs to generate an output token that should be 4034 sent to the peer, that token will be stored in this GSSException and 4035 can be retrieved with this method. 4037 The return value must be null if no such token is generated. It must 4038 not be an empty byte array. 4040 6.8.8. setMinor 4042 public void setMinor(int minorCode, String message) 4044 Used internally by the GSS-API implementation and the underlying 4045 mechanisms to set the minor code and its textual representation. 4047 minorCode The mechanism-specific error code. 4049 message A textual explanation of the mechanism error 4050 code. 4052 6.8.9. toString 4054 public String toString() 4056 Returns a textual representation of both the major and minor status 4057 codes. 4059 6.8.10. getMessage 4061 public String getMessage() 4063 Returns a detailed message of this exception. Overrides 4064 Throwable.getMessage. It is customary in Java to use this method to 4065 obtain exception information. 4067 7. Sample Applications 4069 7.1. Simple GSS Context Initiator 4071 4072 import org.ietf.jgss.*; 4074 /** 4075 * This is a partial sketch for a simple client program that acts 4076 * as a GSS context initiator. It illustrates how to use the Java 4077 * bindings for the GSS-API specified in 4078 * Generic Security Service API Version 2 : Java bindings 4079 * 4080 * 4081 * This code sketch assumes the existence of a GSS-API 4082 * implementation that supports the mechanism that it will need 4083 * and is present as a library package (org.ietf.jgss) either as 4084 * part of the standard JRE or in the CLASSPATH the application 4085 * specifies. 4086 */ 4088 public class SimpleClient { 4090 private String serviceName; // name of peer (i.e., server) 4091 private GSSCredential clientCred = null; 4092 private GSSContext context = null; 4093 private Oid mech; // underlying mechanism to use 4095 private GSSManager mgr = GSSManager.getInstance(); 4097 ... 4098 ... 4100 private void clientActions() { 4101 initializeGSS(); 4102 establishContext(); 4103 doCommunication(); 4104 } 4106 /** 4107 * Acquire credentials for the client. 4108 */ 4109 private void initializeGSS() { 4111 try { 4113 clientCred = mgr.createCredential(null /*default princ*/, 4114 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 4115 mech /* mechanism to use */, 4116 GSSCredential.INITIATE_ONLY /* init context */); 4118 print("GSSCredential created for " + 4119 cred.getName().toString()); 4120 print("Credential lifetime (sec)=" + 4121 cred.getRemainingLifetime()); 4122 } catch (GSSException e) { 4123 print("GSS-API error in credential acquisition: " 4124 + e.getMessage()); 4125 ... 4126 ... 4127 } 4128 ... 4129 ... 4130 } 4132 /** 4133 * Does the security context establishment with the 4134 * server. 4135 */ 4136 private void establishContext() { 4138 byte[] inToken = new byte[0]; 4139 byte[] outToken = null; 4141 try { 4143 GSSName peer = mgr.createName(serviceName, 4144 GSSName.NT_HOSTBASED_SERVICE); 4145 context = mgr.createContext(peer, mech, gssCred, 4146 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 4148 // Will need to support confidentiality 4149 context.requestConf(true); 4151 while (!context.isEstablished()) { 4153 outToken = context.initSecContext(inToken, 0, 4154 inToken.length); 4156 if (outToken != null) 4157 writeGSSToken(outToken); 4159 if (!context.isEstablished()) 4160 inToken = readGSSToken(); 4161 } 4163 GSSName peer = context.getSrcName(); 4164 print("Security context established with " + peer + 4165 " using underlying mechanism " + mech.toString()); 4166 } catch (GSSException e) { 4167 print("GSS-API error during context establishment: " 4168 + e.getMessage()); 4170 // If the exception contains an output token, 4171 // it should be sent to the acceptor. 4172 byte[] outTok = e.getOutputToken(); 4173 if (outTok != null) { 4174 writeGSSToken(outTok); 4175 } 4176 ... 4177 ... 4178 } 4179 ... 4180 ... 4182 } 4184 /** 4185 * Sends some data to the server and reads back the 4186 * response. 4187 */ 4188 private void doCommunication() { 4189 byte[] inToken = null; 4190 byte[] outToken = null; 4191 byte[] buffer; 4193 // Container for multiple input-output arguments to and 4194 // from the per-message routines (e.g., wrap/unwrap). 4195 MessageProp messgInfo = new MessageProp(); 4197 try { 4199 /* 4200 * Now send some bytes to the server to be 4201 * processed. They will be integrity protected 4202 * but not encrypted for privacy. 4203 */ 4205 buffer = readFromFile(); 4207 // Set privacy to "false" and use the default QOP 4208 messgInfo.setPrivacy(false); 4210 outToken = context.wrap(buffer, 0, buffer.length, 4211 messgInfo); 4213 writeGSSToken(outToken); 4215 /* 4216 * Now read the response from the server. 4217 */ 4219 inToken = readGSSToken(); 4220 buffer = context.unwrap(inToken, 0, 4221 inToken.length, messgInfo); 4222 // All ok if no exception was thrown! 4224 GSSName peer = context.getSrcName(); 4226 print("Message from " + peer.toString() 4227 + " arrived."); 4228 print("Was it encrypted? " + 4229 messgInfo.getPrivacy()); 4231 print("Duplicate Token? " + 4232 messgInfo.isDuplicateToken()); 4233 print("Old Token? " + 4234 messgInfo.isOldToken()); 4235 print("Unsequenced Token? " + 4236 messgInfo.isUnseqToken()); 4237 print("Gap Token? " + 4238 messgInfo.isGapToken()); 4239 ... 4240 ... 4241 } catch (GSSException e) { 4242 print("GSS-API error in per-message calls: " 4243 + e.getMessage()); 4244 ... 4245 ... 4246 } 4247 ... 4248 ... 4249 } // end of doCommunication method 4251 ... 4252 ... 4254 } // end of class SimpleClient 4255 4257 7.2. Simple GSS Context Acceptor 4259 4260 import org.ietf.jgss.*; 4262 /** 4263 * This is a partial sketch for a simple server program that acts 4264 * as a GSS context acceptor. It illustrates how to use the Java 4265 * bindings for the GSS-API specified in 4266 * Generic Security Service API Version 2 : Java bindings. 4267 * 4268 * This code sketch assumes the existence of a GSS-API 4269 * implementation that supports the mechanisms that it will need 4270 * and is present as a library package (org.ietf.jgss) either as 4271 * part of the standard JRE or in the CLASSPATH the application 4272 * specifies. 4273 */ 4275 import org.ietf.jgss.*; 4277 public class SimpleServer { 4278 private String serviceName; 4279 private GSSName name; 4280 private GSSCredential cred; 4282 private GSSManager mgr; 4284 ... 4285 ... 4287 /** 4288 * Wait for client connections, establish security contexts 4289 * and provide service. 4290 */ 4291 private void loop() { 4292 ... 4293 ... 4294 mgr = GSSManager.getInstance(); 4296 name = mgr.createName(serviceName, 4297 GSSName.NT_HOSTBASED_SERVICE); 4299 cred = mgr.createCredential(name, 4300 GSSCredential.INDEFINITE_LIFETIME, 4301 null, 4302 GSSCredential.ACCEPT_ONLY); 4304 // Loop infinitely 4305 while (true) { 4306 Socket s = serverSock.accept(); 4308 // Start a new thread to serve this connection 4309 Thread serverThread = new ServerThread(s); 4310 serverThread.start(); 4311 } 4312 } 4314 /** 4315 * Inner class ServerThread whose run() method provides the 4316 * secure service to a connection. 4317 */ 4319 private class ServerThread extends Thread { 4321 ... 4322 ... 4324 /** 4325 * Deals with the connection from one client. It also 4326 * handles all GSSException's thrown while talking to 4327 * this client. 4328 */ 4329 public void run() { 4331 byte[] inToken = null; 4332 byte[] outToken = null; 4333 byte[] buffer; 4335 GSSName peer; 4337 // Container for multiple input-output arguments to 4338 // and from the per-message routines 4339 // (i.e., wrap/unwrap). 4340 MessageProp supplInfo = new MessageProp(); 4341 GSSContext secContext = null; 4343 try { 4344 // Now do the context establishment loop 4345 GSSContext context = mgr.createContext(cred); 4347 while (!context.isEstablished()) { 4349 inToken = readGSSToken(); 4350 outToken = context.acceptSecContext(inToken, 4351 0, inToken.length); 4352 if (outToken != null) 4353 writeGSSToken(outToken); 4354 } 4356 // SimpleServer wants confidentiality to be 4357 // available. Check for it. 4358 if (!context.getConfState()){ 4359 ... 4360 ... 4361 } 4363 GSSName peer = context.getSrcName(); 4364 Oid mech = context.getMech(); 4365 print("Security context established with " + 4366 peer.toString() + 4367 " using underlying mechanism " + 4368 mech.toString() + 4369 " from Provider " + 4370 context.getProvider().getName()); 4372 // Now read the bytes sent by the client to be 4373 // processed. 4375 inToken = readGSSToken(); 4377 // Unwrap the message 4378 buffer = context.unwrap(inToken, 0, 4379 inToken.length, supplInfo); 4380 // All ok if no exception was thrown! 4382 // Print other supplementary per-message status 4383 // information. 4385 print("Message from " + 4386 peer.toString() + " arrived."); 4387 print("Was it encrypted? " + 4388 supplInfo.getPrivacy()); 4389 print("Duplicate Token? " + 4390 supplInfo.isDuplicateToken()); 4391 print("Old Token? " + supplInfo.isOldToken()); 4392 print("Unsequenced Token? " + 4393 supplInfo.isUnseqToken()); 4394 print("Gap Token? " + supplInfo.isGapToken()); 4396 /* 4397 * Now process the bytes and send back an 4398 * encrypted response. 4399 */ 4401 buffer = serverProcess(buffer); 4403 // Encipher it and send it across 4405 supplInfo.setPrivacy(true); // privacy requested 4406 supplInfo.setQOP(0); // default QOP 4407 outToken = context.wrap(buffer, 0, buffer.length, 4408 supplInfo); 4409 writeGSSToken(outToken); 4411 } catch (GSSException e) { 4412 print("GSS-API Error: " + e.getMessage()); 4413 // Alternatively, could call e.getMajorMessage() 4414 // and e.getMinorMessage() 4416 // If the exception contains an output token, 4417 // it should be sent to the initiator. 4418 byte[] outTok = e.getOutputToken(); 4419 if (outTok != null) { 4420 writeGSSToken(outTok); 4421 } 4422 print("Abandoning security context."); 4423 ... 4424 ... 4425 } 4426 ... 4427 ... 4428 } // end of run method in ServerThread 4430 } // end of inner class ServerThread 4432 ... 4433 ... 4435 } // end of class SimpleServer 4436 4438 8. Security Considerations 4440 The Java language security model allows platform providers to have 4441 policy-based fine-grained access control over any resource that an 4442 application wants. When using a Java security manager (such as, but 4443 not limited to, the case of applets running in browsers) the 4444 application code is in a sandbox by default. 4446 Administrators of the platform JRE determine what permissions, if 4447 any, are to be given to source from different codebases. Thus, the 4448 administrator has to be aware of any special requirements that the 4449 GSS provider might have for system resources. For instance, a 4450 Kerberos provider might wish to make a network connection to the Key 4451 Distribution Center (KDC) to obtain initial credentials. This would 4452 not be allowed under the sandbox unless the administrator had granted 4453 permissions for this. Also, note that this granting and checking of 4454 permissions happens transparently to the application and is outside 4455 the scope of this document. 4457 The Java language allows administrators to pre-configure a list of 4458 security service providers in the /lib/security/java.security 4459 file. At runtime, the system approaches these providers in order of 4460 preference when looking for security related services. Applications 4461 have a means to modify this list through methods in the "Security" 4462 class in the "java.security" package. However, since these 4463 modifications would be visible in the entire Java Virtual Machine 4464 (JVM) and thus affect all code executing in it, this operation is not 4465 available in the sandbox and requires special permissions to perform. 4466 Thus, when a GSS application has special needs that are met by a 4467 particular security provider, it has two choices: 4469 1) To install the provider on a JVM-wide basis using the 4470 java.security.Security class and then depend on the system to find 4471 the right provider automatically when the need arises. (This 4472 would require the application to be granted a "insertProvider 4473 SecurityPermission".) 4475 2) To pass an instance of the provider to the local instance of 4476 GSSManager so that only factory calls going through that 4477 GSSManager use the desired provider. (This would not require any 4478 permissions.) 4480 9. IANA Considerations 4482 This document has no actions for IANA. 4484 10. Acknowledgments 4486 This proposed API leverages earlier work performed by the IETF's CAT 4487 WG as outlined in both RFC 2743 [RFC2743] and RFC 2744 [RFC2744]. 4488 Many conceptual definitions, implementation directions, and 4489 explanations have been included from these documents. 4491 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4492 Saltz, and other members of Sun's development team for their helpful 4493 input, comments, and suggestions. 4495 We would also like to thank Joe Salowey, and Michael Smith for many 4496 insightful ideas and suggestions that have contributed to this 4497 document. 4499 11. Changes since RFC 5653 4501 There is a design flaw in the initSecContext and acceptSecContext 4502 methods of the GSSContext class defined in Generic Security Service 4503 API Version 2: Java Bindings Update [RFC5653]. 4505 The methods could either return a token (possibly null if no more 4506 token is needed) when the call succeeds or throw a GSSException if 4507 there is a failure, but NOT both. On the other hand, the C bindings 4508 of GSS-API [RFC2744] can return both, that is to say, a call to 4509 GSS_Init_sec_context() function call can return a major status code, 4510 and at the same time, fill in the output_token argument if there is 4511 one. 4513 Without the ability to emit an error token when there is a failure, a 4514 Java application has no chance to tell the other side what the error 4515 is. For example, a "reject" NegTokenResp token will never be able to 4516 sent out for the SPNEGO mechanism [RFC4178]. 4518 While a Java method can never return a value and throw an exception 4519 at the same time, we can embed the error token inside the exception 4520 so that the caller has a chance to retrieve it. This update adds a 4521 new GSSException constructor to include this token inside a 4522 GSSException object, and a getOutputToken() method to retrieve the 4523 token. The specification for initSecContext and acceptSecContext 4524 methods are updated to describe the new behavior. Various examples 4525 are also updated. 4527 This is a compatible change. New JGSS programs should make use of 4528 this new feature but it is not mandatory. 4530 12. Changes since RFC 2853 4532 This document has following changes: 4534 1) Major GSS Status Code Constant Values 4536 RFC 2853 listed all the GSS status code values in two different 4537 sections: section 4.12.1 defined numeric values for them, and 4538 section 6.8.1 defined them as static constants in the GSSException 4539 class without assigning any values. Due to an inconsistent 4540 ordering between these two sections, all of the GSS major status 4541 codes resulted in misalignment, and a subsequent disagreement 4542 between deployed implementations. 4544 This document defines the numeric values of the GSS status codes 4545 in both sections, while maintaining the original ordering from 4546 section 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status 4547 code values defined in section 4.12.1. The relevant sections in 4548 this document are sections 4.12.1 and 6.8.1. 4550 2) GSS Credential Usage Constant Values 4552 RFC 2853 section 6.3.2 defines static constants for the 4553 GSSCredential usage flags. However, the values of these constants 4554 were not defined anywhere in RFC 2853 [RFC2853]. 4556 This document defines the credential usage values in section 4557 6.3.2. The original ordering of these values from section 6.3.2 4558 of RFC 2853 [RFC2853] is maintained. 4560 3) GSS Host-Based Service Name 4562 RFC 2853 [RFC2853], section 6.2.2, defines the static constant for 4563 the GSS host-based service OID NT_HOSTBASED_SERVICE, using a 4564 deprecated OID value. 4566 This document updates the NT_HOSTBASED_SERVICE OID value in 4567 section 6.2.2 to be consistent with the C-bindings in RFC 2744 4568 [RFC2744]. 4570 13. References 4572 13.1. Normative References 4574 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism 4575 (SPKM)", RFC 2025, October 1996. 4577 [RFC2743] Linn, J., "Generic Security Service Application Program 4578 Interface Version 2, Update 1", RFC 2743, January 2000. 4580 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 4581 C-bindings", RFC 2744, January 2000. 4583 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 4584 Version 5 Generic Security Service Application Program 4585 Interface (GSS-API) Mechanism: Version 2", RFC 4121, July 4586 2005. 4588 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The 4589 Simple and Protected Generic Security Service Application 4590 Program Interface (GSS-API) Negotiation Mechanism", RFC 4591 4178, October 2005. 4593 [RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API 4594 Version 2: Java Bindings Update", RFC 5653, August 2009. 4596 13.2. Informative References 4598 [JLS] Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java 4599 Language Specification", Third Edition, 2005, 4600 . 4602 Authors' Addresses 4604 Mayank D. Upadhyay 4605 Google Inc. 4606 1600 Amphitheatre Parkway 4607 Mountain View, CA 94043 4608 USA 4610 Email: m.d.upadhyay+ietf@gmail.com 4611 Seema Malkani 4612 ActivIdentity Corp. 4613 6623 Dumbarton Circle 4614 Fremont, California 94555 4615 USA 4617 Email: Seema.Malkani@gmail.com 4619 Wang Weijun 4620 Oracle 4621 Building No. 24, Zhongguancun Software Park 4622 Beijing 100193 4623 China 4625 Email: weijun.wang@oracle.com