idnits 2.17.1 draft-ietf-kitten-rfc5653bis-01.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 30, 2014) is 3616 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2853 (Obsoleted by RFC 5653) ** Obsolete normative reference: RFC 5653 (Obsoleted by RFC 8353) Summary: 2 errors (**), 0 flaws (~~), 2 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: December 1, 2014 W. Wang 7 Oracle 8 May 30, 2014 10 Generic Security Service API Version 2: Java Bindings Update 11 draft-ietf-kitten-rfc5653bis-01 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 December 1, 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 97 4.13. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 23 98 4.14. Channel Bindings . . . . . . . . . . . . . . . . . . . . 26 99 4.15. Stream Objects . . . . . . . . . . . . . . . . . . . . . 27 100 4.16. Optional Parameters . . . . . . . . . . . . . . . . . . . 27 101 5. Introduction to GSS-API Classes and Interfaces . . . . . . . 27 102 5.1. GSSManager Class . . . . . . . . . . . . . . . . . . . . 27 103 5.2. GSSName Interface . . . . . . . . . . . . . . . . . . . . 28 104 5.3. GSSCredential Interface . . . . . . . . . . . . . . . . . 29 105 5.4. GSSContext Interface . . . . . . . . . . . . . . . . . . 30 106 5.5. MessageProp Class . . . . . . . . . . . . . . . . . . . . 32 107 5.6. GSSException Class . . . . . . . . . . . . . . . . . . . 32 108 5.7. Oid Class . . . . . . . . . . . . . . . . . . . . . . . . 32 109 5.8. ChannelBinding Class . . . . . . . . . . . . . . . . . . 32 110 6. Detailed GSS-API Class Description . . . . . . . . . . . . . 33 111 6.1. public abstract class GSSManager . . . . . . . . . . . . 33 112 6.1.1. Example Code . . . . . . . . . . . . . . . . . . . . 34 113 6.1.2. getInstance . . . . . . . . . . . . . . . . . . . . . 35 114 6.1.3. getMechs . . . . . . . . . . . . . . . . . . . . . . 35 115 6.1.4. getNamesForMech . . . . . . . . . . . . . . . . . . . 35 116 6.1.5. getMechsForName . . . . . . . . . . . . . . . . . . . 35 117 6.1.6. createName . . . . . . . . . . . . . . . . . . . . . 35 118 6.1.7. createName . . . . . . . . . . . . . . . . . . . . . 36 119 6.1.8. createName . . . . . . . . . . . . . . . . . . . . . 36 120 6.1.9. createName . . . . . . . . . . . . . . . . . . . . . 37 121 6.1.10. createCredential . . . . . . . . . . . . . . . . . . 38 122 6.1.11. createCredential . . . . . . . . . . . . . . . . . . 38 123 6.1.12. createCredential . . . . . . . . . . . . . . . . . . 39 124 6.1.13. createContext . . . . . . . . . . . . . . . . . . . . 39 125 6.1.14. createContext . . . . . . . . . . . . . . . . . . . . 40 126 6.1.15. createContext . . . . . . . . . . . . . . . . . . . . 40 127 6.1.16. addProviderAtFront . . . . . . . . . . . . . . . . . 41 128 6.1.17. Example Code . . . . . . . . . . . . . . . . . . . . 41 129 6.1.18. addProviderAtEnd . . . . . . . . . . . . . . . . . . 43 130 6.1.19. Example Code . . . . . . . . . . . . . . . . . . . . 43 131 6.2. public interface GSSName . . . . . . . . . . . . . . . . 44 132 6.2.1. Example Code . . . . . . . . . . . . . . . . . . . . 44 133 6.2.2. Static Constants . . . . . . . . . . . . . . . . . . 45 134 6.2.3. equals . . . . . . . . . . . . . . . . . . . . . . . 46 135 6.2.4. equals . . . . . . . . . . . . . . . . . . . . . . . 46 136 6.2.5. canonicalize . . . . . . . . . . . . . . . . . . . . 47 137 6.2.6. export . . . . . . . . . . . . . . . . . . . . . . . 47 138 6.2.7. toString . . . . . . . . . . . . . . . . . . . . . . 47 139 6.2.8. getStringNameType . . . . . . . . . . . . . . . . . . 48 140 6.2.9. isAnonymous . . . . . . . . . . . . . . . . . . . . . 48 141 6.2.10. isMN . . . . . . . . . . . . . . . . . . . . . . . . 48 142 6.3. public interface GSSCredential implements Cloneable . . . 48 143 6.3.1. Example Code . . . . . . . . . . . . . . . . . . . . 49 144 6.3.2. Static Constants . . . . . . . . . . . . . . . . . . 50 145 6.3.3. dispose . . . . . . . . . . . . . . . . . . . . . . . 50 146 6.3.4. getName . . . . . . . . . . . . . . . . . . . . . . . 50 147 6.3.5. getName . . . . . . . . . . . . . . . . . . . . . . . 50 148 6.3.6. getRemainingLifetime . . . . . . . . . . . . . . . . 51 149 6.3.7. getRemainingInitLifetime . . . . . . . . . . . . . . 51 150 6.3.8. getRemainingAcceptLifetime . . . . . . . . . . . . . 51 151 6.3.9. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 152 6.3.10. getUsage . . . . . . . . . . . . . . . . . . . . . . 52 153 6.3.11. getMechs . . . . . . . . . . . . . . . . . . . . . . 52 154 6.3.12. add . . . . . . . . . . . . . . . . . . . . . . . . . 52 155 6.3.13. equals . . . . . . . . . . . . . . . . . . . . . . . 53 156 6.4. public interface GSSContext . . . . . . . . . . . . . . . 54 157 6.4.1. Example Code . . . . . . . . . . . . . . . . . . . . 55 158 6.4.2. Static Constants . . . . . . . . . . . . . . . . . . 56 159 6.4.3. initSecContext . . . . . . . . . . . . . . . . . . . 57 160 6.4.4. Example Code . . . . . . . . . . . . . . . . . . . . 58 161 6.4.5. initSecContext . . . . . . . . . . . . . . . . . . . 58 162 6.4.6. Example Code . . . . . . . . . . . . . . . . . . . . 59 163 6.4.7. acceptSecContext . . . . . . . . . . . . . . . . . . 60 164 6.4.8. Example Code . . . . . . . . . . . . . . . . . . . . 61 165 6.4.9. acceptSecContext . . . . . . . . . . . . . . . . . . 62 166 6.4.10. Example Code . . . . . . . . . . . . . . . . . . . . 63 167 6.4.11. isEstablished . . . . . . . . . . . . . . . . . . . . 64 168 6.4.12. dispose . . . . . . . . . . . . . . . . . . . . . . . 65 169 6.4.13. getWrapSizeLimit . . . . . . . . . . . . . . . . . . 65 170 6.4.14. wrap . . . . . . . . . . . . . . . . . . . . . . . . 66 171 6.4.15. wrap . . . . . . . . . . . . . . . . . . . . . . . . 67 172 6.4.16. unwrap . . . . . . . . . . . . . . . . . . . . . . . 68 173 6.4.17. unwrap . . . . . . . . . . . . . . . . . . . . . . . 68 174 6.4.18. getMIC . . . . . . . . . . . . . . . . . . . . . . . 69 175 6.4.19. getMIC . . . . . . . . . . . . . . . . . . . . . . . 70 176 6.4.20. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 70 177 6.4.21. verifyMIC . . . . . . . . . . . . . . . . . . . . . . 71 178 6.4.22. export . . . . . . . . . . . . . . . . . . . . . . . 72 179 6.4.23. requestMutualAuth . . . . . . . . . . . . . . . . . . 73 180 6.4.24. requestReplayDet . . . . . . . . . . . . . . . . . . 73 181 6.4.25. requestSequenceDet . . . . . . . . . . . . . . . . . 73 182 6.4.26. requestCredDeleg . . . . . . . . . . . . . . . . . . 74 183 6.4.27. requestAnonymity . . . . . . . . . . . . . . . . . . 74 184 6.4.28. requestConf . . . . . . . . . . . . . . . . . . . . . 74 185 6.4.29. requestInteg . . . . . . . . . . . . . . . . . . . . 74 186 6.4.30. requestLifetime . . . . . . . . . . . . . . . . . . . 75 187 6.4.31. setChannelBinding . . . . . . . . . . . . . . . . . . 75 188 6.4.32. getCredDelegState . . . . . . . . . . . . . . . . . . 75 189 6.4.33. getMutualAuthState . . . . . . . . . . . . . . . . . 75 190 6.4.34. getReplayDetState . . . . . . . . . . . . . . . . . . 76 191 6.4.35. getSequenceDetState . . . . . . . . . . . . . . . . . 76 192 6.4.36. getAnonymityState . . . . . . . . . . . . . . . . . . 76 193 6.4.37. isTransferable . . . . . . . . . . . . . . . . . . . 76 194 6.4.38. isProtReady . . . . . . . . . . . . . . . . . . . . . 76 195 6.4.39. getConfState . . . . . . . . . . . . . . . . . . . . 77 196 6.4.40. getIntegState . . . . . . . . . . . . . . . . . . . . 77 197 6.4.41. getLifetime . . . . . . . . . . . . . . . . . . . . . 77 198 6.4.42. getSrcName . . . . . . . . . . . . . . . . . . . . . 77 199 6.4.43. getTargName . . . . . . . . . . . . . . . . . . . . . 77 200 6.4.44. getMech . . . . . . . . . . . . . . . . . . . . . . . 77 201 6.4.45. getDelegCred . . . . . . . . . . . . . . . . . . . . 78 202 6.4.46. isInitiator . . . . . . . . . . . . . . . . . . . . . 78 203 6.5. public class MessageProp . . . . . . . . . . . . . . . . 78 204 6.5.1. Constructors . . . . . . . . . . . . . . . . . . . . 78 205 6.5.2. getQOP . . . . . . . . . . . . . . . . . . . . . . . 79 206 6.5.3. getPrivacy . . . . . . . . . . . . . . . . . . . . . 79 207 6.5.4. getMinorStatus . . . . . . . . . . . . . . . . . . . 79 208 6.5.5. getMinorString . . . . . . . . . . . . . . . . . . . 79 209 6.5.6. setQOP . . . . . . . . . . . . . . . . . . . . . . . 79 210 6.5.7. setPrivacy . . . . . . . . . . . . . . . . . . . . . 80 211 6.5.8. isDuplicateToken . . . . . . . . . . . . . . . . . . 80 212 6.5.9. isOldToken . . . . . . . . . . . . . . . . . . . . . 80 213 6.5.10. isUnseqToken . . . . . . . . . . . . . . . . . . . . 80 214 6.5.11. isGapToken . . . . . . . . . . . . . . . . . . . . . 80 215 6.5.12. setSupplementaryStates . . . . . . . . . . . . . . . 80 216 6.6. public class ChannelBinding . . . . . . . . . . . . . . . 81 217 6.6.1. Constructors . . . . . . . . . . . . . . . . . . . . 81 218 6.6.2. getInitiatorAddress . . . . . . . . . . . . . . . . . 82 219 6.6.3. getAcceptorAddress . . . . . . . . . . . . . . . . . 82 220 6.6.4. getApplicationData . . . . . . . . . . . . . . . . . 82 221 6.6.5. equals . . . . . . . . . . . . . . . . . . . . . . . 83 222 6.7. public class Oid . . . . . . . . . . . . . . . . . . . . 83 223 6.7.1. Constructors . . . . . . . . . . . . . . . . . . . . 83 224 6.7.2. toString . . . . . . . . . . . . . . . . . . . . . . 84 225 6.7.3. equals . . . . . . . . . . . . . . . . . . . . . . . 84 226 6.7.4. getDER . . . . . . . . . . . . . . . . . . . . . . . 84 227 6.7.5. containedIn . . . . . . . . . . . . . . . . . . . . . 84 228 6.8. public class GSSException extends Exception . . . . . . . 85 229 6.8.1. Static Constants . . . . . . . . . . . . . . . . . . 85 230 6.8.2. Constructors . . . . . . . . . . . . . . . . . . . . 88 231 6.8.3. getMajor . . . . . . . . . . . . . . . . . . . . . . 89 232 6.8.4. getMinor . . . . . . . . . . . . . . . . . . . . . . 89 233 6.8.5. getMajorString . . . . . . . . . . . . . . . . . . . 89 234 6.8.6. getMinorString . . . . . . . . . . . . . . . . . . . 89 235 6.8.7. getOutputToken . . . . . . . . . . . . . . . . . . . 89 236 6.8.8. setMinor . . . . . . . . . . . . . . . . . . . . . . 90 237 6.8.9. toString . . . . . . . . . . . . . . . . . . . . . . 90 238 6.8.10. getMessage . . . . . . . . . . . . . . . . . . . . . 90 239 7. Sample Applications . . . . . . . . . . . . . . . . . . . . . 90 240 7.1. Simple GSS Context Initiator . . . . . . . . . . . . . . 90 241 7.2. Simple GSS Context Acceptor . . . . . . . . . . . . . . . 94 242 8. Security Considerations . . . . . . . . . . . . . . . . . . . 98 243 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 99 244 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 99 245 11. Changes since RFC 5653 . . . . . . . . . . . . . . . . . . . 99 246 12. Changes since RFC 2853 . . . . . . . . . . . . . . . . . . . 100 247 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 101 248 13.1. Normative References . . . . . . . . . . . . . . . . . . 101 249 13.2. Informative References . . . . . . . . . . . . . . . . . 101 250 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 101 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 426 The GSS-API allows delegation to be controlled by the initiating 427 application via the requestCredDeleg method before the first call to 428 init has been issued. Some mechanisms do not support delegation, and 429 for such mechanisms, attempts by an application to enable delegation 430 are ignored. 432 The acceptor of a security context, for which the initiator enabled 433 delegation, can check if delegation was enabled by using the 434 getCredDelegState method of the GSSContext interface. In cases when 435 it is enabled, the delegated credential object can be obtained by 436 calling the getDelegCred method. The obtained GSSCredential object 437 may then be used to initiate subsequent GSS-API security contexts as 438 an agent or delegate of the initiator. If the original initiator's 439 identity is "A" and the delegate's identity is "B", then, depending 440 on the underlying mechanism, the identity embodied by the delegated 441 credential may be either "A" or "B acting for A". 443 For many mechanisms that support delegation, a simple boolean does 444 not provide enough control. Examples of additional aspects of 445 delegation control that a mechanism might provide to an application 446 are duration of delegation, network addresses from which delegation 447 is valid, and constraints on the tasks that may be performed by a 448 delegate. Such controls are presently outside the scope of the GSS- 449 API. GSS-API implementations supporting mechanisms offering 450 additional controls should provide extension routines that allow 451 these controls to be exercised (perhaps by modifying the initiator's 452 GSS-API credential object prior to its use in establishing a 453 context). However, the simple delegation control provided by GSS-API 454 should always be able to override other mechanism-specific delegation 455 controls. If the application instructs the GSSContext object that 456 delegation is not desired, then the implementation must not permit 457 delegation to occur. This is an exception to the general rule that a 458 mechanism may enable services even if they are not requested -- 459 delegation may only be provided at the explicit request of the 460 application. 462 3.2. Mutual Authentication 464 Usually, a context acceptor will require that a context initiator 465 authenticate itself so that the acceptor may make an access-control 466 decision prior to performing a service for the initiator. In some 467 cases, the initiator may also request that the acceptor authenticate 468 itself. GSS-API allows the initiating application to request this 469 mutual authentication service by calling the requestMutualAuth method 470 of the GSSContext interface with a "true" parameter before making the 471 first call to init. The initiating application is informed as to 472 whether or not the context acceptor has authenticated itself. Note 473 that some mechanisms may not support mutual authentication, and other 474 mechanisms may always perform mutual authentication, whether or not 475 the initiating application requests it. In particular, mutual 476 authentication may be required by some mechanisms in order to support 477 replay or out-of-sequence message detection, and for such mechanisms, 478 a request for either of these services will automatically enable 479 mutual authentication. 481 3.3. Replay and Out-of-Sequence Detection 483 The GSS-API may provide detection of mis-ordered messages once a 484 security context has been established. Protection may be applied to 485 messages by either application, by calling either getMIC or wrap 486 methods of the GSSContext interface, and verified by the peer 487 application by calling verifyMIC or unwrap for the peer's GSSContext 488 object. 490 The getMIC method calculates a cryptographic checksum of an 491 application message, and returns that checksum in a token. The 492 application should pass both the token and the message to the peer 493 application, which presents them to the verifyMIC method of the 494 peer's GSSContext object. 496 The wrap method calculates a cryptographic checksum of an application 497 message, and places both the checksum and the message inside a single 498 token. The application should pass the token to the peer 499 application, which presents it to the unwrap method of the peer's 500 GSSContext object to extract the message and verify the checksum. 502 Either pair of routines may be capable of detecting out-of-sequence 503 message delivery or the duplication of messages. Details of such 504 mis-ordered messages are indicated through supplementary query 505 methods of the MessageProp object that is filled in by each of these 506 routines. 508 A mechanism need not maintain a list of all tokens that have been 509 processed in order to support these status codes. A typical 510 mechanism might retain information about only the most recent "N" 511 tokens processed, allowing it to distinguish duplicates and missing 512 tokens within the most recent "N" messages; the receipt of a token 513 older than the most recent "N" would result in the isOldToken method 514 of the instance of MessageProp to return "true". 516 3.4. Anonymous Authentication 518 In certain situations, an application may wish to initiate the 519 authentication process to authenticate a peer, without revealing its 520 own identity. As an example, consider an application providing 521 access to a database containing medical information and offering 522 unrestricted access to the service. A client of such a service might 523 wish to authenticate the service (in order to establish trust in any 524 information retrieved from it), but might not wish the service to be 525 able to obtain the client's identity (perhaps due to privacy concerns 526 about the specific inquiries, or perhaps simply to avoid being placed 527 on mailing-lists). 529 In normal use of the GSS-API, the initiator's identity is made 530 available to the acceptor as a result of the context establishment 531 process. However, context initiators may request that their identity 532 not be revealed to the context acceptor. Many mechanisms do not 533 support anonymous authentication, and for such mechanisms, the 534 request will not be honored. An authentication token will still be 535 generated, but the application is always informed if a requested 536 service is unavailable, and has the option to abort context 537 establishment if anonymity is valued above the other security 538 services that would require a context to be established. 540 In addition to informing the application that a context is 541 established anonymously (via the isAnonymous method of the GSSContext 542 class), the getSrcName method of the acceptor's GSSContext object 543 will, for such contexts, return a reserved internal-form name, 544 defined by the implementation. 546 The toString method for a GSSName object representing an anonymous 547 entity will return a printable name. The returned value will be 548 syntactically distinguishable from any valid principal name supported 549 by the implementation. The associated name-type object identifier 550 will be an oid representing the value of NT_ANONYMOUS. This name- 551 type oid will be defined as a public, static Oid object of the 552 GSSName class. The printable form of an anonymous name should be 553 chosen such that it implies anonymity, since this name may appear in, 554 for example, audit logs. For example, the string "" might 555 be a good choice, if no valid printable names supported by the 556 implementation can begin with "<" and end with ">". 558 When using the equal method of the GSSName interface, and one of the 559 operands is a GSSName instance representing an anonymous entity, the 560 method must return "false". 562 3.5. Confidentiality 564 If a GSSContext supports the confidentiality service, wrap method may 565 be used to encrypt application messages. Messages are selectively 566 encrypted, under the control of the setPrivacy method of the 567 MessageProp object used in the wrap method. 569 3.6. Inter-process Context Transfer 571 GSS-APIv2 provides functionality that allows a security context to be 572 transferred between processes on a single machine. These are 573 implemented using the export method of GSSContext and a byte array 574 constructor of the same class. The most common use for such a 575 feature is a client-server design where the server is implemented as 576 a single process that accepts incoming security contexts, which then 577 launches child processes to deal with the data on these contexts. In 578 such a design, the child processes must have access to the security 579 context object created within the parent so that they can use per- 580 message protection services and delete the security context when the 581 communication session ends. 583 Since the security context data structure is expected to contain 584 sequencing information, it is impractical in general to share a 585 context between processes. Thus, the GSSContext interface provides 586 an export method that the process, which currently owns the context, 587 can call to declare that it has no intention to use the context 588 subsequently, and to create an inter-process token containing 589 information needed by the adopting process to successfully recreate 590 the context. After successful completion of export, the original 591 security context is made inaccessible to the calling process by GSS- 592 API, and any further usage of this object will result in failures. 593 The originating process transfers the inter-process token to the 594 adopting process, which creates a new GSSContext object using the 595 byte array constructor. The properties of the context are equivalent 596 to that of the original context. 598 The inter-process token may contain sensitive data from the original 599 security context (including cryptographic keys). Applications using 600 inter-process tokens to transfer security contexts must take 601 appropriate steps to protect these tokens in transit. 603 Implementations are not required to support the inter-process 604 transfer of security contexts. Calling the isTransferable method of 605 the GSSContext interface will indicate if the context object is 606 transferable. 608 3.7. The Use of Incomplete Contexts 610 Some mechanisms may allow the per-message services to be used before 611 the context establishment process is complete. For example, a 612 mechanism may include sufficient information in its initial context- 613 level tokens for the context acceptor to immediately decode messages 614 protected with wrap or getMIC. For such a mechanism, the initiating 615 application need not wait until subsequent context-level tokens have 616 been sent and received before invoking the per-message protection 617 services. 619 An application can invoke the isProtReady method of the GSSContext 620 class to determine if the per-message services are available in 621 advance of complete context establishment. Applications wishing to 622 use per-message protection services on partially established contexts 623 should query this method before attempting to invoke wrap or getMIC. 625 4. Calling Conventions 627 Java provides the implementors with not just a syntax for the 628 language, but also an operational environment. For example, memory 629 is automatically managed and does not require application 630 intervention. These language features have allowed for a simpler API 631 and have led to the elimination of certain GSS-API functions. 633 Moreover, the JCA defines a provider model that allows for 634 implementation-independent access to security services. Using this 635 model, applications can seamlessly switch between different 636 implementations and dynamically add new services. The GSS-API 637 specification leverages these concepts by the usage of providers for 638 the mechanism implementations. 640 4.1. Package Name 642 The classes and interfaces defined in this document reside in the 643 package called "org.ietf.jgss". Applications that wish to make use 644 of this API should import this package name as shown in section 7. 646 4.2. Provider Framework 648 The Java security API's use a provider architecture that allows 649 applications to be implementation independent and security API 650 implementations to be modular and extensible. The 651 java.security.Provider class is an abstract class that a vendor 652 extends. This class maps various properties that represent different 653 security services that are available to the names of the actual 654 vendor classes that implement those services. When requesting a 655 service, an application simply specifies the desired provider and the 656 API delegates the request to service classes available from that 657 provider. 659 Using the Java security provider model insulates applications from 660 implementation details of the services they wish to use. 661 Applications can switch between providers easily and new providers 662 can be added as needed, even at runtime. 664 The GSS-API may use providers to find components for specific 665 underlying security mechanisms. For instance, a particular provider 666 might contain components that will allow the GSS-API to support the 667 Kerberos v5 mechanism [RFC4121] and another might contain components 668 to support the Simple Public-Key GSS-API Mechanism (SPKM) [RFC2025]. 669 By delegating mechanism-specific functionality to the components 670 obtained from providers, the GSS-API can be extended to support an 671 arbitrary list of mechanism. 673 How the GSS-API locates and queries these providers is beyond the 674 scope of this document and is being deferred to a Service Provider 675 Interface (SPI) specification. The availability of such an SPI 676 specification is not mandatory for the adoption of this API 677 specification nor is it mandatory to use providers in the 678 implementation of a GSS-API framework. However, by using the 679 provider framework together with an SPI specification, one can create 680 an extensible and implementation-independent GSS-API framework. 682 4.3. Integer Types 684 All numeric values are declared as "int" primitive Java type. The 685 Java specification guarantees that this will be a 32-bit two's 686 complement signed number. 688 Throughout this API, the "boolean" primitive Java type is used 689 wherever a boolean value is required or returned. 691 4.4. Opaque Data Types 693 Java byte arrays are used to represent opaque data types that are 694 consumed and produced by the GSS-API in the form of tokens. Java 695 arrays contain a length field that enables the users to easily 696 determine their size. The language has automatic garbage collection 697 that alleviates the need by developers to release memory and 698 simplifies buffer ownership issues. 700 4.5. Strings 702 The String object will be used to represent all textual data. The 703 Java String object transparently treats all characters as two-byte 704 Unicode characters, which allows support for many locals. All 705 routines returning or accepting textual data will use the String 706 object. 708 4.6. Object Identifiers 710 An Oid object will be used to represent Universal Object Identifiers 711 (Oids). Oids are ISO-defined, hierarchically globally interpretable 712 identifiers used within the GSS-API framework to identify security 713 mechanisms and name formats. The Oid object can be created from a 714 string representation of its dot notation (e.g., "1.3.6.1.5.6.2") as 715 well as from its ASN.1 DER encoding. Methods are also provided to 716 test equality and provide the DER representation for the object. 718 An important feature of the Oid class is that its instances are 719 immutable -- i.e., there are no methods defined that allow one to 720 change the contents of an Oid. This property allows one to treat 721 these objects as "statics" without the need to perform copies. 723 Certain routines allow the usage of a default oid. A "null" value 724 can be used in those cases. 726 4.7. Object Identifier Sets 728 The Java bindings represent object identifier sets as arrays of Oid 729 objects. All Java arrays contain a length field, which allows for 730 easy manipulation and reference. 732 In order to support the full functionality of RFC 2743 [RFC2743], the 733 Oid class includes a method that checks for existence of an Oid 734 object within a specified array. This is equivalent in functionality 735 to gss_test_oid_set_member. The use of Java arrays and Java's 736 automatic garbage collection has eliminated the need for the 737 following routines: gss_create_empty_oid_set, gss_release_oid_set, 738 and gss_add_oid_set_member. Java GSS-API implementations will not 739 contain them. Java's automatic garbage collection and the immutable 740 property of the Oid object eliminates the memory management issues of 741 the C counterpart. 743 Whenever a default value for an Object Identifier Set is required, a 744 "null" value can be used. Please consult the detailed method 745 description for details. 747 4.8. Credentials 749 GSS-API credentials are represented by the GSSCredential interface. 750 The interface contains several constructs to allow for the creation 751 of most common credential objects for the initiator and the acceptor. 752 Comparisons are performed using the interface's "equals" method. The 753 following general description of GSS-API credentials is included from 754 the C-bindings specification: 756 GSS-API credentials can contain mechanism-specific principal 757 authentication data for multiple mechanisms. A GSS-API credential 758 is composed of a set of credential-elements, each of which is 759 applicable to a single mechanism. A credential may contain at 760 most one credential-element for each supported mechanism. A 761 credential-element identifies the data needed by a single 762 mechanism to authenticate a single principal, and conceptually 763 contains two credential-references that describe the actual 764 mechanism-specific authentication data, one to be used by GSS-API 765 for initiating contexts, and one to be used for accepting 766 contexts. For mechanisms that do not distinguish between acceptor 767 and initiator credentials, both references would point to the same 768 underlying mechanism-specific authentication data. 770 Credentials describe a set of mechanism-specific principals, and give 771 their holder the ability to act as any of those principals. All 772 principal identities asserted by a single GSS-API credential should 773 belong to the same entity, although enforcement of this property is 774 an implementation-specific matter. A single GSSCredential object 775 represents all the credential elements that have been acquired. 777 The creation of an GSSContext object allows the value of "null" to be 778 specified as the GSSCredential input parameter. This will indicate a 779 desire by the application to act as a default principal. While 780 individual GSS-API implementations are free to determine such default 781 behavior as appropriate to the mechanism, the following default 782 behavior by these routines is recommended for portability: 784 For the initiator side of the context: 786 1) If there is only a single principal capable of initiating security 787 contexts for the chosen mechanism that the application is 788 authorized to act on behalf of, then that principal shall be used; 789 otherwise, 791 2) If the platform maintains a concept of a default network-identity 792 for the chosen mechanism, and if the application is authorized to 793 act on behalf of that identity for the purpose of initiating 794 security contexts, then the principal corresponding to that 795 identity shall be used; otherwise, 797 3) If the platform maintains a concept of a default local identity, 798 and provides a means to map local identities into network- 799 identities for the chosen mechanism, and if the application is 800 authorized to act on behalf of the network-identity image of the 801 default local identity for the purpose of initiating security 802 contexts using the chosen mechanism, then the principal 803 corresponding to that identity shall be used; otherwise, 805 4) A user-configurable default identity should be used. 807 For the acceptor side of the context: 809 1) If there is only a single authorized principal identity capable of 810 accepting security contexts for the chosen mechanism, then that 811 principal shall be used; otherwise, 813 2) If the mechanism can determine the identity of the target 814 principal by examining the context-establishment token processed 815 during the accept method, and if the accepting application is 816 authorized to act as that principal for the purpose of accepting 817 security contexts using the chosen mechanism, then that principal 818 identity shall be used; otherwise, 820 3) If the mechanism supports context acceptance by any principal, and 821 if mutual authentication was not requested, any principal that the 822 application is authorized to accept security contexts under using 823 the chosen mechanism may be used; otherwise, 825 4) A user-configurable default identity shall be used. 827 The purpose of the above rules is to allow security contexts to be 828 established by both initiator and acceptor using the default behavior 829 whenever possible. Applications requesting default behavior are 830 likely to be more portable across mechanisms and implementations than 831 ones that instantiate an GSSCredential object representing a specific 832 identity. 834 4.9. Contexts 836 The GSSContext interface is used to represent one end of a GSS-API 837 security context, storing state information appropriate to that end 838 of the peer communication, including cryptographic state information. 839 The instantiation of the context object is done differently by the 840 initiator and the acceptor. After the context has been instantiated, 841 the initiator may choose to set various context options that will 842 determine the characteristics of the desired security context. When 843 all the application-desired characteristics have been set, the 844 initiator will call the initSecContext method, which will produce a 845 token for consumption by the peer's acceptSecContext method. It is 846 the responsibility of the application to deliver the authentication 847 token(s) between the peer applications for processing. Upon 848 completion of the context-establishment phase, context attributes can 849 be retrieved, by both the initiator and acceptor, using the accessor 850 methods. These will reflect the actual attributes of the established 851 context. At this point, the context can be used by the application 852 to apply cryptographic services to its data. 854 4.10. Authentication Tokens 856 A token is a caller-opaque type that GSS-API uses to maintain 857 synchronization between each end of the GSS-API security context. 858 The token is a cryptographically protected octet-string, generated by 859 the underlying mechanism at one end of a GSS-API security context for 860 use by the peer mechanism at the other end. Encapsulation (if 861 required) within the application protocol and transfer of the token 862 are the responsibility of the peer applications. 864 Java GSS-API uses byte arrays to represent authentication tokens. 865 Overloaded methods exist that allow the caller to supply input and 866 output streams that will be used for the reading and writing of the 867 token data. 869 4.11. Inter-Process Tokens 871 Certain GSS-API routines are intended to transfer data between 872 processes in multi-process programs. These routines use a caller- 873 opaque octet-string, generated by the GSS-API in one process for use 874 by the GSS-API in another process. The calling application is 875 responsible for transferring such tokens between processes. Note 876 that, while GSS-API implementors are encouraged to avoid placing 877 sensitive information within inter-process tokens, or to 878 cryptographically protect them, many implementations will be unable 879 to avoid placing key material or other sensitive data within them. 880 It is the application's responsibility to ensure that inter-process 881 tokens are protected in transit, and transferred only to processes 882 that are trustworthy. An inter-process token is represented using a 883 byte array emitted from the export method of the GSSContext 884 interface. The receiver of the inter-process token would initialize 885 an GSSContext object with this token to create a new context. Once a 886 context has been exported, the GSSContext object is invalidated and 887 is no longer available. 889 4.12. Error Reporting 891 RFC 2743 [RFC2743] defined the usage of major and minor status values 892 for the signaling of GSS-API errors. The major code, also called GSS 893 status code, is used to signal errors at the GSS-API level, 894 independent of the underlying mechanism(s). The minor status value 895 or Mechanism status code, is a mechanism-defined error value 896 indicating a mechanism-specific error code. 898 Java GSS-API uses exceptions implemented by the GSSException class to 899 signal both minor and major error values. Both mechanism-specific 900 errors and GSS-API level errors are signaled through instances of 901 this class. The usage of exceptions replaces the need for major and 902 minor codes to be used within the API calls. The GSSException class 903 also contains methods to obtain textual representations for both the 904 major and minor values, which is equivalent to the functionality of 905 gss_display_status. 907 4.12.1. GSS Status Codes 909 GSS status codes indicate errors that are independent of the 910 underlying mechanism(s) used to provide the security service. The 911 errors that can be indicated via a GSS status code are generic API 912 routine errors (errors that are defined in the GSS-API 913 specification). These bindings take advantage of the Java exceptions 914 mechanism, thus, eliminating the need for calling errors. 916 A GSS status code indicates a single fatal generic API error from the 917 routine that has thrown the GSSException. Using exceptions announces 918 that a fatal error has occurred during the execution of the method. 919 The GSS-API operational model also allows for the signaling of 920 supplementary status information from the per-message calls. These 921 need to be handled as return values since using exceptions is not 922 appropriate for informatory or warning-like information. The methods 923 that are capable of producing supplementary information are the two 924 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 925 These methods fill the supplementary status codes in the MessageProp 926 object that was passed in. 928 A GSSException object, along with providing the functionality for 929 setting of the various error codes and translating them into textual 930 representation, also contains the definitions of all the numeric 931 error values. The following table lists the definitions of error 932 codes: 934 Table: GSS Status Codes 936 +----------------------+-------+------------------------------------+ 937 | Name | Value | Meaning | 938 +----------------------+-------+------------------------------------+ 939 | BAD_BINDINGS | 1 | Incorrect channel bindings were | 940 | | | supplied. | 941 | | | | 942 | BAD_MECH | 2 | An unsupported mechanism was | 943 | | | requested. | 944 | | | | 945 | BAD_NAME | 3 | An invalid name was supplied. | 946 | | | | 947 | BAD_NAMETYPE | 4 | A supplied name was of an | 948 | | | unsupported type. | 949 | | | | 950 | BAD_STATUS | 5 | An invalid status code was | 951 | | | supplied. | 952 | | | | 953 | BAD_MIC | 6 | A token had an invalid MIC. | 954 | | | | 955 | CONTEXT_EXPIRED | 7 | The context has expired. | 956 | | | | 957 | CREDENTIALS_EXPIRED | 8 | The referenced credentials have | 958 | | | expired. | 959 | | | | 960 | DEFECTIVE_CREDENTIAL | 9 | A supplied credential was invalid. | 961 | | | | 962 | DEFECTIVE_TOKEN | 10 | A supplied token was invalid. | 963 | | | | 964 | FAILURE | 11 | Miscellaneous failure, unspecified | 965 | | | at the GSS-API level. | 966 | | | | 967 | NO_CONTEXT | 12 | Invalid context has been supplied. | 968 | | | | 969 | NO_CRED | 13 | No credentials were supplied, or | 970 | | | the credentials were unavailable | 971 | | | or inaccessible. | 972 | | | | 973 | BAD_QOP | 14 | The quality-of-protection (QOP) | 974 | | | requested could not be provided. | 975 | | | | 976 | UNAUTHORIZED | 15 | The operation is forbidden by the | 977 | | | local security policy. | 978 | | | | 979 | UNAVAILABLE | 16 | The operation or option is | 980 | | | unavailable. | 981 | | | | 982 | DUPLICATE_ELEMENT | 17 | The requested credential element | 983 | | | already exists. | 984 | | | | 985 | NAME_NOT_MN | 18 | The provided name was not a | 986 | | | mechanism name. | 987 +----------------------+-------+------------------------------------+ 989 The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN, 990 UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException only if 991 detected during context establishment, in which case it is a fatal 992 error. (During per-message calls, these values are indicated as 993 supplementary information contained in the MessageProp object.) They 994 are: 996 +-----------------+-------+-----------------------------------------+ 997 | Name | Value | Meaning | 998 +-----------------+-------+-----------------------------------------+ 999 | DUPLICATE_TOKEN | 19 | The token was a duplicate of an earlier | 1000 | | | version. | 1001 | | | | 1002 | OLD_TOKEN | 20 | The token's validity period has | 1003 | | | expired. | 1004 | | | | 1005 | UNSEQ_TOKEN | 21 | A later token has already been | 1006 | | | processed. | 1007 | | | | 1008 | GAP_TOKEN | 22 | The expected token was not received. | 1009 +-----------------+-------+-----------------------------------------+ 1011 The GSS major status code of FAILURE is used to indicate that the 1012 underlying mechanism detected an error for which no specific GSS 1013 status code is defined. The mechanism-specific status code can 1014 provide more details about the error. 1016 The different major status codes that can be contained in the 1017 GSSException object thrown by the methods in this specification are 1018 the same as the major status codes returned by the corresponding 1019 calls in RFC 2743 [RFC2743]. 1021 4.12.2. Mechanism-Specific Status Codes 1023 Mechanism-specific status codes are communicated in two ways, they 1024 are part of any GSSException thrown from the mechanism-specific layer 1025 to signal a fatal error, or they are part of the MessageProp object 1026 that the per-message calls use to signal non-fatal errors. 1028 A default value of 0 in either the GSSException object or the 1029 MessageProp object will be used to represent the absence of any 1030 mechanism-specific status code. 1032 4.12.3. Supplementary Status Codes 1034 Supplementary status codes are confined to the per-message methods of 1035 the GSSContext interface. Because of the informative nature of these 1036 errors it is not appropriate to use exceptions to signal them. 1037 Instead, the per-message operations of the GSSContext interface 1038 return these values in a MessageProp object. 1040 The MessageProp class defines query methods that return boolean 1041 values indicating the following supplementary states: 1043 Table: Supplementary Status Methods 1045 +------------------+------------------------------------------------+ 1046 | Method Name | Meaning when "true" is returned | 1047 +------------------+------------------------------------------------+ 1048 | isDuplicateToken | The token was a duplicate of an earlier token. | 1049 | | | 1050 | isOldToken | The token's validity period has expired. | 1051 | | | 1052 | isUnseqToken | A later token has already been processed. | 1053 | | | 1054 | isGapToken | An expected per-message token was not | 1055 | | received. | 1056 +------------------+------------------------------------------------+ 1058 A "true" return value for any of the above methods indicates that the 1059 token exhibited the specified property. The application must 1060 determine the appropriate course of action for these supplementary 1061 values. They are not treated as errors by the GSS-API. 1063 4.13. Names 1065 A name is used to identify a person or entity. GSS-API authenticates 1066 the relationship between a name and the entity claiming the name. 1068 Since different authentication mechanisms may employ different 1069 namespaces for identifying their principals, GSS-API's naming support 1070 is necessarily complex in multi-mechanism environments (or even in 1071 some single-mechanism environments where the underlying mechanism 1072 supports multiple namespaces). 1074 Two distinct conceptual representations are defined for names: 1076 1) A GSS-API form represented by implementations of the GSSName 1077 interface: A single GSSName object may contain multiple names from 1078 different namespaces, but all names should refer to the same 1079 entity. An example of such an internal name would be the name 1080 returned from a call to the getName method of the GSSCredential 1081 interface, when applied to a credential containing credential 1082 elements for multiple authentication mechanisms employing 1083 different namespaces. This GSSName object will contain a distinct 1084 name for the entity for each authentication mechanism. 1086 For GSS-API implementations supporting multiple namespaces, 1087 GSSName implementations must contain sufficient information to 1088 determine the namespace to which each primitive name belongs. 1090 2) Mechanism-specific contiguous byte array and string forms: 1091 Different GSSName initialization methods are provided to handle 1092 both byte array and string formats and to accommodate various 1093 calling applications and name types. These formats are capable of 1094 containing only a single name (from a single namespace). 1095 Contiguous string names are always accompanied by an object 1096 identifier specifying the namespace to which the name belongs, and 1097 their format is dependent on the authentication mechanism that 1098 employs that name. The string name forms are assumed to be 1099 printable, and may therefore be used by GSS-API applications for 1100 communication with their users. The byte array name formats are 1101 assumed to be in non-printable formats (e.g., the byte array 1102 returned from the export method of the GSSName interface). 1104 A GSSName object can be converted to a contiguous representation by 1105 using the toString method. This will guarantee that the name will be 1106 converted to a printable format. Different initialization methods in 1107 the GSSName interface are defined allowing support for multiple 1108 syntaxes for each supported namespace, and allowing users the freedom 1109 to choose a preferred name representation. The toString method 1110 should use an implementation-chosen printable syntax for each 1111 supported name type. To obtain the printable name type, 1112 getStringNameType method can be used. 1114 There is no guarantee that calling the toString method on the GSSName 1115 interface will produce the same string form as the original imported 1116 string name. Furthermore, it is possible that the name was not even 1117 constructed from a string representation. The same applies to 1118 namespace identifiers, which may not necessarily survive unchanged 1119 after a journey through the internal name form. An example of this 1120 might be a mechanism that authenticates X.500 names, but provides an 1121 algorithmic mapping of Internet DNS names into X.500. That 1122 mechanism's implementation of GSSName might, when presented with a 1123 DNS name, generate an internal name that contained both the original 1124 DNS name and the equivalent X.500 name. Alternatively, it might only 1125 store the X.500 name. In the latter case, the toString method of 1126 GSSName would most likely generate a printable X.500 name, rather 1127 than the original DNS name. 1129 The context acceptor can obtain a GSSName object representing the 1130 entity performing the context initiation (through the usage of 1131 getSrcName method). Since this name has been authenticated by a 1132 single mechanism, it contains only a single name (even if the 1133 internal name presented by the context initiator to the GSSContext 1134 object had multiple components). Such names are termed internal- 1135 mechanism names (or MNs), and the names emitted by GSSContext 1136 interface in the getSrcName and getTargName are always of this type. 1137 Since some applications may require MNs without wanting to incur the 1138 overhead of an authentication operation, creation methods are 1139 provided that take not only the name buffer and name type, but also 1140 the mechanism oid for which this name should be created. When 1141 dealing with an existing GSSName object, the canonicalize method may 1142 be invoked to convert a general internal name into an MN. 1144 GSSName objects can be compared using their equal method, which 1145 returns "true" if the two names being compared refer to the same 1146 entity. This is the preferred way to perform name comparisons 1147 instead of using the printable names that a given GSS-API 1148 implementation may support. Since GSS-API assumes that all primitive 1149 names contained within a given internal name refer to the same 1150 entity, equal can return "true" if the two names have at least one 1151 primitive name in common. If the implementation embodies knowledge 1152 of equivalence relationships between names taken from different 1153 namespaces, this knowledge may also allow successful comparisons of 1154 internal names containing no overlapping primitive elements. 1156 When used in large access control lists, the overhead of creating a 1157 GSSName object on each name and invoking the equal method on each 1158 name from the Access Control List (ACL) may be prohibitive. As an 1159 alternative way of supporting this case, GSS-API defines a special 1160 form of the contiguous byte array name, which may be compared 1161 directly (byte by byte). Contiguous names suitable for comparison 1162 are generated by the export method. Exported names may be re- 1163 imported by using the byte array constructor and specifying the 1164 NT_EXPORT_NAME as the name type object identifier. The resulting 1165 GSSName name will also be a MN. 1167 The GSSName interface defines public static Oid objects representing 1168 the standard name types. Structurally, an exported name object 1169 consists of a header containing an OID identifying the mechanism that 1170 authenticated the name, and a trailer containing the name itself, 1171 where the syntax of the trailer is defined by the individual 1172 mechanism specification. Detailed description of the format is 1173 specified in the language-independent GSS-API specification 1174 [RFC2743]. 1176 Note that the results obtained by using the equals method will in 1177 general be different from those obtained by invoking canonicalize and 1178 export, and then comparing the byte array output. The first series 1179 of operation determines whether two (unauthenticated) names identify 1180 the same principal; the second whether a particular mechanism would 1181 authenticate them as the same principal. These two operations will 1182 in general give the same results only for MNs. 1184 It is important to note that the above are guidelines as to how 1185 GSSName implementations should behave, and are not intended to be 1186 specific requirements of how name objects must be implemented. The 1187 mechanism designers are free to decide on the details of their 1188 implementations of the GSSName interface as long as the behavior 1189 satisfies the above guidelines. 1191 4.14. Channel Bindings 1193 GSS-API supports the use of user-specified tags to identify a given 1194 context to the peer application. These tags are intended to be used 1195 to identify the particular communications channel that carries the 1196 context. Channel bindings are communicated to the GSS-API using the 1197 ChannelBinding object. The application may use byte arrays to 1198 specify the application data to be used in the channel binding as 1199 well as using instances of the InetAddress. The InetAddress for the 1200 initiator and/or acceptor can be used within an instance of a 1201 ChannelBinding. ChannelBinding can be set for the GSSContext object 1202 using the setChannelBinding method before the first call to init or 1203 accept has been performed. Unless the setChannelBinding method has 1204 been used to set the ChannelBinding for a GSSContext object, "null" 1205 ChannelBinding will be assumed. InetAddress is currently the only 1206 address type defined within the Java platform and as such, it is the 1207 only one supported within the ChannelBinding class. Applications 1208 that use other types of addresses can include them as part of the 1209 application-specific data. 1211 Conceptually, the GSS-API concatenates the initiator and acceptor 1212 address information, and the application-supplied byte array to form 1213 an octet-string. The mechanism calculates a Message Integrity Code 1214 (MIC) over this octet-string and binds the MIC to the context 1215 establishment token emitted by the init method of the GSSContext 1216 interface. The same bindings are set by the context acceptor for its 1217 GSSContext object and during processing of the accept method, a MIC 1218 is calculated in the same way. The calculated MIC is compared with 1219 that found in the token, and if the MICs differ, accept will throw a 1220 GSSException with the major code set to BAD_BINDINGS, and the context 1221 will not be established. Some mechanisms may include the actual 1222 channel binding data in the token (rather than just a MIC); 1223 applications should therefore not use confidential data as channel- 1224 binding components. 1226 Individual mechanisms may impose additional constraints on addresses 1227 that may appear in channel bindings. For example, a mechanism may 1228 verify that the initiator address field of the channel binding 1229 contains the correct network address of the host system. Portable 1230 applications should therefore ensure that they either provide correct 1231 information for the address fields, or omit the setting of the 1232 addressing information. 1234 4.15. Stream Objects 1236 The context object provides overloaded methods that use input and 1237 output streams as the means to convey authentication and per-message 1238 GSS-API tokens. It is important to note that the streams are 1239 expected to contain the usual GSS-API tokens, which would otherwise 1240 be handled through the usage of byte arrays. The tokens are expected 1241 to have a definite start and an end. The callers are responsible for 1242 ensuring that the supplied streams will not block, or expect to block 1243 until a full token is processed by the GSS-API method. Only a single 1244 GSS-API token will be processed per invocation of the stream-based 1245 method. 1247 The usage of streams allows the callers to have control and 1248 management of the supplied buffers. Because streams are non- 1249 primitive objects, the callers can make the streams as complicated or 1250 as simple as desired simply by using the streams defined in the 1251 java.io package or creating their own through the use of inheritance. 1252 This will allow for the application's greatest flexibility. 1254 4.16. Optional Parameters 1256 Whenever the application wishes to omit an optional parameter the 1257 "null" value shall be used. The detailed method descriptions 1258 indicate which parameters are optional. Method overloading has also 1259 been used as a technique to indicate default parameters. 1261 5. Introduction to GSS-API Classes and Interfaces 1263 This section presents a brief description of the classes and 1264 interfaces that constitute the GSS-API. The implementations of these 1265 are obtained from the CLASSPATH defined by the application. If Java 1266 GSS becomes part of the standard Java APIs, then these classes will 1267 be available by default on all systems as part of the JRE's system 1268 classes. 1270 This section also shows the corresponding RFC 2743 [RFC2743] 1271 functionality implemented by each of the classes. Detailed 1272 description of these classes and their methods is presented in 1273 section 6 1275 5.1. GSSManager Class 1277 This abstract class serves as a factory to instantiate 1278 implementations of the GSS-API interfaces and also provides methods 1279 to make queries about underlying security mechanisms. 1281 A default implementation can be obtained using the static method 1282 getInstance(). Applications that desire to provide their own 1283 implementation of the GSSManager class can simply extend the abstract 1284 class themselves. 1286 This class contains equivalents of the following RFC 2743 [RFC2743] 1287 routines: 1289 +----------------------------+-------------------------+------------+ 1290 | RFC 2743 Routine | Function | Section(s) | 1291 +----------------------------+-------------------------+------------+ 1292 | gss_import_name | Create an internal name | 6.1.6- | 1293 | | from the supplied | 6.1.9 | 1294 | | information. | | 1295 | | | | 1296 | gss_acquire_cred | Acquire credential for | 6.1.10- | 1297 | | use. | 6.1.12 | 1298 | | | | 1299 | gss_import_sec_context | Create a previously | 6.1.15 | 1300 | | exported context. | | 1301 | | | | 1302 | gss_indicate_mechs | List the mechanisms | 6.1.3 | 1303 | | supported by this GSS- | | 1304 | | API implementation. | | 1305 | | | | 1306 | gss_inquire_mechs_for_name | List the mechanisms | 6.1.5 | 1307 | | supporting the | | 1308 | | specified name type. | | 1309 | | | | 1310 | gss_inquire_names_for_mech | List the name types | 6.1.4 | 1311 | | supported by the | | 1312 | | specified mechanism. | | 1313 +----------------------------+-------------------------+------------+ 1315 5.2. GSSName Interface 1317 GSS-API names are represented in the Java bindings through the 1318 GSSName interface. Different name formats and their definitions are 1319 identified with Universal Object Identifiers (oids). The format of 1320 the names can be derived based on the unique oid of each name type. 1321 The following GSS-API routines are provided by the GSSName interface: 1323 +-----------------------+------------------------------+------------+ 1324 | RFC 2743 Routine | Function | Section(s) | 1325 +-----------------------+------------------------------+------------+ 1326 | gss_display_name | Covert internal name | 6.2.7 | 1327 | | representation to text | | 1328 | | format. | | 1329 | | | | 1330 | gss_compare_name | Compare two internal names. | 6.2.3, | 1331 | | | 6.2.4 | 1332 | | | | 1333 | gss_release_name | Release resources associated | N/A | 1334 | | with the internal name. | | 1335 | | | | 1336 | gss_canonicalize_name | Convert an internal name to | 6.2.5 | 1337 | | a mechanism name. | | 1338 | | | | 1339 | gss_export_name | Convert a mechanism name to | 6.2.6 | 1340 | | export format. | | 1341 | | | | 1342 | gss_duplicate_name | Create a copy of the | N/A | 1343 | | internal name. | | 1344 +-----------------------+------------------------------+------------+ 1346 The gss_release_name call is not provided as Java does its own 1347 garbage collection. The gss_duplicate_name call is also redundant; 1348 the GSSName interface has no mutator methods that can change the 1349 state of the object so it is safe for sharing across threads. 1351 5.3. GSSCredential Interface 1353 The GSSCredential interface is responsible for the encapsulation of 1354 GSS-API credentials. Credentials identify a single entity and 1355 provide the necessary cryptographic information to enable the 1356 creation of a context on behalf of that entity. A single credential 1357 may contain multiple mechanism-specific credentials, each referred to 1358 as a credential element. The GSSCredential interface provides the 1359 functionality of the following GSS-API routines: 1361 +--------------------------+---------------------------+------------+ 1362 | RFC 2743 Routine | Function | Section(s) | 1363 +--------------------------+---------------------------+------------+ 1364 | gss_add_cred | Constructs credentials | 6.3.12 | 1365 | | incrementally. | | 1366 | | | | 1367 | gss_inquire_cred | Obtain information about | 6.3.4- | 1368 | | credential. | 6.3.11 | 1369 | | | | 1370 | gss_inquire_cred_by_mech | Obtain per-mechanism | 6.3.5- | 1371 | | information about a | 6.3.10 | 1372 | | credential. | | 1373 | | | | 1374 | gss_release_cred | Dispose of credentials | 6.3.3 | 1375 | | after use. | | 1376 +--------------------------+---------------------------+------------+ 1378 5.4. GSSContext Interface 1380 This interface encapsulates the functionality of context-level calls 1381 required for security context establishment and management between 1382 peers as well as the per-message services offered to applications. A 1383 context is established between a pair of peers and allows the usage 1384 of security services on a per-message basis on application data. It 1385 is created over a single security mechanism. The GSSContext 1386 interface provides the functionality of the following GSS-API 1387 routines: 1389 +------------------------+-----------------------------+------------+ 1390 | RFC 2743 Routine | Function | Section(s) | 1391 +------------------------+-----------------------------+------------+ 1392 | gss_init_sec_context | Initiate the creation of a | 6.4.3- | 1393 | | security context with a | 6.4.6 | 1394 | | peer. | | 1395 | | | | 1396 | gss_accept_sec_context | Accept a security context | 6.4.7- | 1397 | | initiated by a peer. | 6.4.10 | 1398 | | | | 1399 | gss_delete_sec_context | Destroy a security context. | 6.4.12 | 1400 | | | | 1401 | gss_context_time | Obtain remaining context | 6.4.41 | 1402 | | time. | | 1403 | | | | 1404 | gss_inquire_context | Obtain context | 6.4.32- | 1405 | | characteristics. | 6.4.46 | 1406 | | | | 1407 | gss_wrap_size_limit | Determine token-size limit | 6.4.13 | 1408 | | for gss_wrap. | | 1409 | | | | 1410 | gss_export_sec_context | Transfer security context | 6.4.22 | 1411 | | to another process. | | 1412 | | | | 1413 | gss_get_mic | Calculate a cryptographic | 6.4.18, | 1414 | | Message Integrity Code | 6.4.19 | 1415 | | (MIC) for a message. | | 1416 | | | | 1417 | gss_verify_mic | Verify integrity on a | 6.4.20, | 1418 | | received message. | 6.4.21 | 1419 | | | | 1420 | gss_wrap | Attach a MIC to a message | 6.4.14, | 1421 | | and optionally encrypt the | 6.4.15 | 1422 | | message content. | | 1423 | | | | 1424 | gss_unwrap | Obtain a previously wrapped | 6.4.16, | 1425 | | application message | 6.4.17 | 1426 | | verifying its integrity and | | 1427 | | optionally decrypting it. | | 1428 +------------------------+-----------------------------+------------+ 1430 The functionality offered by the gss_process_context_token routine 1431 has not been included in the Java bindings specification. The 1432 corresponding functionality of gss_delete_sec_context has also been 1433 modified to not return any peer tokens. This has been proposed in 1434 accordance to the recommendations stated in RFC 2743 [RFC2743]. 1435 GSSContext does offer the functionality of destroying the locally 1436 stored context information. 1438 5.5. MessageProp Class 1440 This helper class is used in the per-message operations on the 1441 context. An instance of this class is created by the application and 1442 then passed into the per-message calls. In some cases, the 1443 application conveys information to the GSS-API implementation through 1444 this object and in other cases the GSS-API returns information to the 1445 application by setting it in this object. See the description of the 1446 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1447 GSSContext interfaces for details. 1449 5.6. GSSException Class 1451 Exceptions are used in the Java bindings to signal fatal errors to 1452 the calling applications. This replaces the major and minor codes 1453 used in the C-bindings specification as a method of signaling 1454 failures. The GSSException class handles both minor and major codes, 1455 as well as their translation into textual representation. All GSS- 1456 API methods are declared as throwing this exception. 1458 +--------------------+----------------------------+-----------------+ 1459 | RFC 2743 Routine | Function | Section | 1460 +--------------------+----------------------------+-----------------+ 1461 | gss_display_status | Retrieve textual | 6.8.5, 6.8.6, | 1462 | | representation of error | 6.8.9, 6.8.10 | 1463 | | codes. | | 1464 +--------------------+----------------------------+-----------------+ 1466 5.7. Oid Class 1468 This utility class is used to represent Universal Object Identifiers 1469 and their associated operations. GSS-API uses object identifiers to 1470 distinguish between security mechanisms and name types. This class, 1471 aside from being used whenever an object identifier is needed, 1472 implements the following GSS-API functionality: 1474 +-------------------------+-------------------------------+---------+ 1475 | RFC 2743 Routine | Function | Section | 1476 +-------------------------+-------------------------------+---------+ 1477 | gss_test_oid_set_member | Determine if the specified | 6.7.5 | 1478 | | oid is part of a set of oids. | | 1479 +-------------------------+-------------------------------+---------+ 1481 5.8. ChannelBinding Class 1483 An instance of this class is used to specify channel binding 1484 information to the GSSContext object before the start of a security 1485 context establishment. The application may use a byte array to 1486 specify application data to be used in the channel binding as well as 1487 to use instances of the InetAddress. InetAddress is currently the 1488 only address type defined within the Java platform and as such, it is 1489 the only one supported within the ChannelBinding class. Applications 1490 that use other types of addresses can include them as part of the 1491 application data. 1493 6. Detailed GSS-API Class Description 1495 This section lists a detailed description of all the public methods 1496 that each of the GSS-API classes and interfaces must provide. 1498 6.1. public abstract class GSSManager 1500 The GSSManager class is an abstract class that serves as a factory 1501 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1502 also provides methods for applications to determine what mechanisms 1503 are available from the GSS implementation and what name types these 1504 mechanisms support. An instance of the default GSSManager subclass 1505 may be obtained through the static method getInstance(), but 1506 applications are free to instantiate other subclasses of GSSManager. 1508 All but one method in this class are declared abstract. This means 1509 that subclasses have to provide the complete implementation for those 1510 methods. The only exception to this is the static method 1511 getInstance(), which will have platform-specific code to return an 1512 instance of the default subclass. 1514 Platform providers of GSS are required not to add any constructors to 1515 this class, private, public, or protected. This will ensure that all 1516 subclasses invoke only the default constructor provided to the base 1517 class by the compiler. 1519 A subclass extending the GSSManager abstract class may be implemented 1520 as a modular provider-based layer that utilizes some well-known 1521 service provider specification. The GSSManager API provides the 1522 application with methods to set provider preferences on such an 1523 implementation. These methods also allow the implementation to throw 1524 a well-defined exception in case provider-based configuration is not 1525 supported. Applications that expect to be portable should be aware 1526 of this and recover cleanly by catching the exception. 1528 It is envisioned that there will be three most common ways in which 1529 providers will be used: 1531 1) The application does not care about what provider is used (the 1532 default case). 1534 2) The application wants a particular provider to be used 1535 preferentially, either for a particular mechanism or all the time, 1536 irrespective of the mechanism. 1538 3) The application wants to use the locally configured providers as 1539 far as possible, but if support is missing for one or more 1540 mechanisms, then it wants to fall back on its own provider. 1542 The GSSManager class has two methods that enable these modes of 1543 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1544 have the effect of creating an ordered list of pairs 1545 where each pair indicates a preference of provider for a given oid. 1547 The use of these methods does not require any knowledge of whatever 1548 service provider specification the GSSManager subclass follows. It 1549 is hoped that these methods will serve the needs of most 1550 applications. Additional methods may be added to an extended 1551 GSSManager that could be part of a service provider specification 1552 that is standardized later. 1554 6.1.1. Example Code 1556 1557 GSSManager mgr = GSSManager.getInstance(); 1559 // What mechs are available to us? 1561 Oid[] supportedMechs = mgr.getMechs(); 1563 // Set a preference for the provider to be used when support 1564 // is needed for the mechanisms: 1565 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1567 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1568 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1570 Provider p = (Provider) (new com.foo.security.Provider()); 1572 mgr.addProviderAtFront(p, krb); 1573 mgr.addProviderAtFront(p, spkm1); 1575 // What name types does this spkm implementation support? 1576 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1577 1579 6.1.2. getInstance 1581 public static GSSManager getInstance() 1583 Returns the default GSSManager implementation. 1585 6.1.3. getMechs 1587 public abstract Oid[] getMechs() 1589 Returns an array of Oid objects indicating the mechanisms available 1590 to GSS-API callers. A "null" value is returned when no mechanism are 1591 available (an example of this would be when mechanism are dynamically 1592 configured, and currently no mechanisms are installed). 1594 6.1.4. getNamesForMech 1596 public abstract Oid[] getNamesForMech(Oid mech) 1597 throws GSSException 1599 Returns name type Oid's supported by the specified mechanism. 1601 Parameters: 1603 mech The Oid object for the mechanism to query. 1605 6.1.5. getMechsForName 1607 public abstract Oid[] getMechsForName(Oid nameType) 1609 Returns an array of Oid objects corresponding to the mechanisms that 1610 support the specific name type. "null" is returned when no mechanisms 1611 are found to support the specified name type. 1613 Parameters: 1615 nameType The Oid object for the name type. 1617 6.1.6. createName 1619 public abstract GSSName createName(String nameStr, Oid nameType) 1620 throws GSSException 1622 Factory method to convert a contiguous string name from the specified 1623 namespace to a GSSName object. In general, the GSSName object 1624 created will not be an MN; two examples that are exceptions to this 1625 are when the namespace type parameter indicates NT_EXPORT_NAME or 1626 when the GSS-API implementation is not multi-mechanism. 1628 Parameters: 1630 nameStr The string representing a printable form of the 1631 name to create. 1633 nameType The Oid specifying the namespace of the printable 1634 name is supplied. Note that nameType serves to 1635 describe and qualify the interpretation of the 1636 input nameStr, it does not necessarily imply a 1637 type for the output GSSName implementation. The 1638 "null" value can be used to specify that a 1639 mechanism-specific default printable syntax 1640 should be assumed by each mechanism that examines 1641 nameStr. 1643 6.1.7. createName 1645 public abstract GSSName createName(byte[] name, Oid nameType) 1646 throws GSSException 1648 Factory method to convert a contiguous byte array containing a name 1649 from the specified namespace to a GSSName object. In general, the 1650 GSSName object created will not be an MN; two examples that are 1651 exceptions to this are when the namespace type parameter indicates 1652 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1653 mechanism. 1655 Parameters: 1657 name The byte array containing the name to create. 1659 nameType The Oid specifying the namespace of the name 1660 supplied in the byte array. Note that nameType 1661 serves to describe and qualify the interpretation 1662 of the input name byte array; it does not 1663 necessarily imply a type for the output GSSName 1664 implementation. The "null" value can be used to 1665 specify that a mechanism-specific default syntax 1666 should be assumed by each mechanism that examines 1667 the byte array. 1669 6.1.8. createName 1671 public abstract GSSName createName(String nameStr, Oid nameType, 1672 Oid mech) throws GSSException 1674 Factory method to convert a contiguous string name from the specified 1675 namespace to a GSSName object that is a mechanism name (MN). In 1676 other words, this method is a utility that does the equivalent of two 1677 steps: the createName described in section 6.1.6, and then also the 1678 GSSName.canonicalize() described in section 6.2.5. 1680 Parameters: 1682 nameStr The string representing a printable form of the 1683 name to create. 1685 nameType The Oid specifying the namespace of the printable 1686 name supplied. Note that nameType serves to 1687 describe and qualify the interpretation of the 1688 input nameStr; it does not necessarily imply a 1689 type for the output GSSName implementation. The 1690 "null" value can be used to specify that a 1691 mechanism-specific default printable syntax 1692 should be assumed when the mechanism examines 1693 nameStr. 1695 mech Oid specifying the mechanism for which this name 1696 should be created. 1698 6.1.9. createName 1700 public abstract GSSName createName(byte[] name, Oid nameType, 1701 Oid mech) throws GSSException 1703 Factory method to convert a contiguous byte array containing a name 1704 from the specified namespace to a GSSName object that is an MN. In 1705 other words, this method is a utility that does the equivalent of two 1706 steps: the createName described in section 6.1.7, and then also the 1707 GSSName.canonicalize() described in section 6.2.5. 1709 Parameters: 1711 name The byte array representing the name to create. 1713 nameType The Oid specifying the namespace of the name 1714 supplied in the byte array. Note that nameType 1715 serves to describe and qualify the interpretation 1716 of the input name byte array, it does not 1717 necessarily imply a type for the output GSSName 1718 implementation. The "null" value can be used to 1719 specify that a mechanism-specific default syntax 1720 should be assumed by each mechanism that examines 1721 the byte array. 1723 mech Oid specifying the mechanism for which this name 1724 should be created. 1726 6.1.10. createCredential 1728 public abstract GSSCredential createCredential(int usage) 1729 throws GSSException 1731 Factory method for acquiring default credentials. This will cause 1732 the GSS-API to use system-specific defaults for the set of 1733 mechanisms, name, and a DEFAULT lifetime. 1735 Parameters: 1737 usage The intended usage for this credential object. 1738 The value of this parameter must be one of: 1740 GSSCredential.INITIATE_AND_ACCEPT(0), 1741 GSSCredential.INITIATE_ONLY(1), or 1742 GSSCredential.ACCEPT_ONLY(2) 1744 6.1.11. createCredential 1746 public abstract GSSCredential createCredential(GSSName aName, 1747 int lifetime, Oid mech, int usage) 1748 throws GSSException 1750 Factory method for acquiring a single mechanism credential. 1752 Parameters: 1754 aName Name of the principal for whom this credential is 1755 to be acquired. Use "null" to specify the 1756 default principal. 1758 lifetime The number of seconds that credentials should 1759 remain valid. Use 1760 GSSCredential.INDEFINITE_LIFETIME to request that 1761 the credentials have the maximum permitted 1762 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1763 request default credential lifetime. 1765 mech The oid of the desired mechanism. Use "(Oid) 1766 null" to request the default mechanism(s). 1768 usage The intended usage for this credential object. 1769 The value of this parameter must be one of: 1771 GSSCredential.INITIATE_AND_ACCEPT(0), 1772 GSSCredential.INITIATE_ONLY(1), or 1773 GSSCredential.ACCEPT_ONLY(2) 1775 6.1.12. createCredential 1777 public abstract GSSCredential createCredential(GSSName aName, 1778 int lifetime, Oid[] mechs, int usage) 1779 throws GSSException 1781 Factory method for acquiring credentials over a set of mechanisms. 1782 Acquires credentials for each of the mechanisms specified in the 1783 array called mechs. To determine the list of mechanisms' for which 1784 the acquisition of credentials succeeded, the caller should use the 1785 GSSCredential.getMechs() method. 1787 Parameters: 1789 aName Name of the principal for whom this credential is 1790 to be acquired. Use "null" to specify the 1791 default principal. 1793 lifetime The number of seconds that credentials should 1794 remain valid. Use 1795 GSSCredential.INDEFINITE_LIFETIME to request that 1796 the credentials have the maximum permitted 1797 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 1798 request default credential lifetime. 1800 mechs The array of mechanisms over which the credential 1801 is to be acquired. Use "(Oid[]) null" for 1802 requesting a system-specific default set of 1803 mechanisms. 1805 usage The intended usage for this credential object. 1806 The value of this parameter must be one of: 1808 GSSCredential.INITIATE_AND_ACCEPT(0), 1809 GSSCredential.INITIATE_ONLY(1), or 1810 GSSCredential.ACCEPT_ONLY(2) 1812 6.1.13. createContext 1814 public abstract GSSContext createContext(GSSName peer, Oid mech, 1815 GSSCredential myCred, int lifetime) 1816 throws GSSException 1818 Factory method for creating a context on the initiator's side. 1819 Context flags may be modified through the mutator methods prior to 1820 calling GSSContext.initSecContext(). 1822 Parameters: 1824 peer Name of the target peer. 1826 mech Oid of the desired mechanism. Use "(Oid) null" 1827 to request the default mechanism. 1829 myCred Credentials of the initiator. Use "null" to act 1830 as a default initiator principal. 1832 lifetime The request lifetime, in seconds, for the 1833 context. Use GSSContext.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 Parameters: 1848 myCred Credentials for the acceptor. Use "null" to act 1849 as a default acceptor principal. 1851 6.1.15. createContext 1853 public abstract GSSContext createContext(byte[] interProcessToken) 1854 throws GSSException 1856 Factory method for creating a previously exported context. The 1857 context properties will be determined from the input token and can't 1858 be modified through the set methods. 1860 Parameters: 1862 interProcessToken The token previously emitted from the export 1863 method. 1865 6.1.16. addProviderAtFront 1867 public abstract void addProviderAtFront(Provider p, Oid mech) 1868 throws GSSException 1870 This method is used to indicate to the GSSManager that the 1871 application would like a particular provider to be used ahead of all 1872 others when support is desired for the given mechanism. When a value 1873 of "null" is used instead of an Oid for the mechanism, the GSSManager 1874 must use the indicated provider ahead of all others no matter what 1875 the mechanism is. Only when the indicated provider does not support 1876 the needed mechanism should the GSSManager move on to a different 1877 provider. 1879 Calling this method repeatedly preserves the older settings but 1880 lowers them in preference thus forming an ordered list of provider 1881 and Oid pairs that grows at the top. 1883 Calling addProviderAtFront with a null Oid will remove all previous 1884 preferences that were set for this provider in the GSSManager 1885 instance. Calling addProviderAtFront with a non-null Oid will remove 1886 any previous preference that was set using this mechanism and this 1887 provider together. 1889 If the GSSManager implementation does not support an SPI with a 1890 pluggable provider architecture, it should throw a GSSException with 1891 the status code GSSException.UNAVAILABLE to indicate that the 1892 operation is unavailable. 1894 Parameters: 1896 p The provider instance that should be used 1897 whenever support is needed for mech. 1899 mech The mechanism for which the provider is being 1900 set. 1902 6.1.17. Example Code 1904 Suppose an application desired that the provider A always be checked 1905 first when any mechanism is needed, it would call: 1907 1908 GSSManager mgr = GSSManager.getInstance(); 1909 // mgr may at this point have its own pre-configured list 1910 // of provider preferences. The following will prepend to 1911 // any such list: 1913 mgr.addProviderAtFront(A, null); 1914 1916 Now if it also desired that the mechanism of Oid m1 always be 1917 obtained from the provider B before the previously set A was checked, 1918 it would call: 1920 1921 mgr.addProviderAtFront(B, m1); 1922 1924 The GSSManager would then first check with B if m1 was needed. In 1925 case B did not provide support for m1, the GSSManager would continue 1926 on to check with A. If any mechanism m2 is needed where m2 is 1927 different from m1, then the GSSManager would skip B and check with A 1928 directly. 1930 Suppose, at a later time, the following call is made to the same 1931 GSSManager instance: 1933 1934 mgr.addProviderAtFront(B, null) 1935 1937 then the previous setting with the pair (B, m1) is subsumed by this 1938 and should be removed. Effectively, the list of preferences now 1939 becomes {(B, null), (A, null), ... //followed by the pre-configured 1940 list. 1942 Please note, however, that the following call: 1944 1945 mgr.addProviderAtFront(A, m3) 1946 1948 does not subsume the previous setting of (A, null), and the list will 1949 effectively become {(A, m3), (B, null), (A, null), ...} 1951 6.1.18. addProviderAtEnd 1953 public abstract void addProviderAtEnd(Provider p, Oid mech) 1954 throws GSSException 1956 This method is used to indicate to the GSSManager that the 1957 application would like a particular provider to be used if no other 1958 provider can be found that supports the given mechanism. When a 1959 value of "null" is used instead of an Oid for the mechanism, the 1960 GSSManager must use the indicated provider for any mechanism. 1962 Calling this method repeatedly preserves the older settings, but 1963 raises them above newer ones in preference thus forming an ordered 1964 list of providers and Oid pairs that grows at the bottom. Thus, the 1965 older provider settings will be utilized first before this one is. 1967 If there are any previously existing preferences that conflict with 1968 the preference being set here, then the GSSManager should ignore this 1969 request. 1971 If the GSSManager implementation does not support an SPI with a 1972 pluggable provider architecture, it should throw a GSSException with 1973 the status code GSSException.UNAVAILABLE to indicate that the 1974 operation is unavailable. 1976 Parameters: 1978 p The provider instance that should be used 1979 whenever support is needed for mech. 1981 mech The mechanism for which the provider is being 1982 set. 1984 6.1.19. Example Code 1986 Suppose an application desired that when a mechanism of Oid m1 is 1987 needed, the system default providers always be checked first, and 1988 only when they do not support m1 should a provider A be checked. It 1989 would then make the call: 1991 1992 GSSManager mgr = GSSManager.getInstance(); 1994 mgr.addProviderAtEnd(A, m1); 1995 1996 Now, if it also desired that for all mechanisms the provider B be 1997 checked after all configured providers have been checked, it would 1998 then call: 2000 2001 mgr.addProviderAtEnd(B, null); 2002 2004 Effectively, the list of preferences now becomes {..., (A, m1), (B, 2005 null)}. 2007 Suppose, at a later time, the following call is made to the same 2008 GSSManager instance: 2010 2011 mgr.addProviderAtEnd(B, m2) 2012 2014 then the previous setting with the pair (B, null) subsumes this; 2015 therefore, this request should be ignored. The same would happen if 2016 a request is made for the already existing pairs of (A, m1) or (B, 2017 null). 2019 Please note, however, that the following call: 2021 2022 mgr.addProviderAtEnd(A, null) 2023 2025 is not subsumed by the previous setting of (A, m1) and the list will 2026 effectively become {..., (A, m1), (B, null), (A, null)}. 2028 6.2. public interface GSSName 2030 This interface encapsulates a single GSS-API principal entity. 2031 Different name formats and their definitions are identified with 2032 Universal Object Identifiers (Oids). The format of the names can be 2033 derived based on the unique oid of its namespace type. 2035 6.2.1. Example Code 2037 Included below are code examples utilizing the GSSName interface. 2038 The code below creates a GSSName, converts it to a mechanism name 2039 (MN), performs a comparison, obtains a printable representation of 2040 the name, exports it and then re-imports to obtain a new GSSName. 2042 2043 GSSManager mgr = GSSManager.getInstance(); 2045 // create a host-based service name 2046 GSSName name = mgr.createName("service@host", 2047 GSSName.NT_HOSTBASED_SERVICE); 2049 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 2051 GSSName mechName = name.canonicalize(krb5); 2053 // the above two steps are equivalent to the following 2054 GSSName mechName = mgr.createName("service@host", 2055 GSSName.NT_HOSTBASED_SERVICE, krb5); 2057 // perform name comparison 2058 if (name.equals(mechName)) 2059 print("Names are equals."); 2061 // obtain textual representation of name and its printable 2062 // name type 2063 print(mechName.toString() + 2064 mechName.getStringNameType().toString()); 2066 // export and re-import the name 2067 byte[] exportName = mechName.export(); 2069 // create a new name object from the exported buffer 2070 GSSName newName = mgr.createName(exportName, 2071 GSSName.NT_EXPORT_NAME); 2072 2074 6.2.2. Static Constants 2076 public static final Oid NT_HOSTBASED_SERVICE 2078 Oid indicating a host-based service name form. It is used to 2079 represent services associated with host computers. This name form is 2080 constructed using two elements, "service" and "hostname", as follows: 2082 service@hostname 2084 Values for the "service" element are registered with the IANA. It 2085 represents the following value: { iso(1) member-body(2) Unites 2086 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2087 service_name(4) } 2089 public static final Oid NT_USER_NAME 2090 Name type to indicate a named user on a local system. It represents 2091 the following value: { iso(1) member-body(2) United States(840) 2092 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2094 public static final Oid NT_MACHINE_UID_NAME 2096 Name type to indicate a numeric user identifier corresponding to a 2097 user on a local system (e.g., Uid). It represents the following 2098 value: { iso(1) member-body(2) United States(840) mit(113554) 2099 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2101 public static final Oid NT_STRING_UID_NAME 2103 Name type to indicate a string of digits representing the numeric 2104 user identifier of a user on a local system. It represents the 2105 following value: { iso(1) member-body(2) United States(840) 2106 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2108 public static final Oid NT_ANONYMOUS 2110 Name type for representing an anonymous entity. It represents the 2111 following value: { iso(1), org(3), dod(6), internet(1), security(5), 2112 nametypes(6), gss-anonymous-name(3) } 2114 public static final Oid NT_EXPORT_NAME 2116 Name type used to indicate an exported name produced by the export 2117 method. It represents the following value: { iso(1), org(3), dod(6), 2118 internet(1), security(5), nametypes(6), gss-api-exported-name(4) } 2120 6.2.3. equals 2122 public boolean equals(GSSName another) throws GSSException 2124 Compares two GSSName objects to determine whether they refer to the 2125 same entity. This method may throw a GSSException when the names 2126 cannot be compared. If either of the names represents an anonymous 2127 entity, the method will return "false". 2129 Parameters: 2131 another GSSName object with which to compare. 2133 6.2.4. equals 2135 public boolean equals(Object another) 2136 A variation of the equals method, described in section 6.2.3, that is 2137 provided to override the Object.equals() method that the implementing 2138 class will inherit. The behavior is exactly the same as that in 2139 section 6.2.3 except that no GSSException is thrown; instead, "false" 2140 will be returned in the situation where an error occurs. (Note that 2141 the Java language specification requires that two objects that are 2142 equal according to the equals(Object) method must return the same 2143 integer result when the hashCode() method is called on them.) 2145 Parameters: 2147 another GSSName object with which to compare. 2149 6.2.5. canonicalize 2151 public GSSName canonicalize(Oid mech) throws GSSException 2153 Creates a mechanism name (MN) from an arbitrary internal name. This 2154 is equivalent to using the factory methods described in sections 2155 6.1.8 or 6.1.9 that take the mechanism name as one of their 2156 parameters. 2158 Parameters: 2160 mech The oid for the mechanism for which the canonical 2161 form of the name is requested. 2163 6.2.6. export 2165 public byte[] export() throws GSSException 2167 Returns a canonical contiguous byte representation of a mechanism 2168 name (MN), suitable for direct, byte-by-byte comparison by 2169 authorization functions. If the name is not an MN, implementations 2170 may throw a GSSException with the NAME_NOT_MN status code. If an 2171 implementation chooses not to throw an exception, it should use some 2172 system-specific default mechanism to canonicalize the name and then 2173 export it. The format of the header of the output buffer is 2174 specified in RFC 2743 [RFC2743]. 2176 6.2.7. toString 2178 public String toString() 2180 Returns a textual representation of the GSSName object. To retrieve 2181 the printed name format, which determines the syntax of the returned 2182 string, the getStringNameType method can be used. 2184 6.2.8. getStringNameType 2186 public Oid getStringNameType() throws GSSException 2188 Returns the oid representing the type of name returned through the 2189 toString method. Using this oid, the syntax of the printable name 2190 can be determined. 2192 6.2.9. isAnonymous 2194 public boolean isAnonymous() 2196 Tests if this name object represents an anonymous entity. Returns 2197 "true" if this is an anonymous name. 2199 6.2.10. isMN 2201 public boolean isMN() 2203 Tests if this name object contains only one mechanism element and is 2204 thus a mechanism name as defined by RFC 2743 [RFC2743]. 2206 6.3. public interface GSSCredential implements Cloneable 2208 This interface encapsulates the GSS-API credentials for an entity. A 2209 credential contains all the necessary cryptographic information to 2210 enable the creation of a context on behalf of the entity that it 2211 represents. It may contain multiple, distinct, mechanism-specific 2212 credential elements, each containing information for a specific 2213 security mechanism, but all referring to the same entity. 2215 A credential may be used to perform context initiation, acceptance, 2216 or both. 2218 GSS-API implementations must impose a local access-control policy on 2219 callers to prevent unauthorized callers from acquiring credentials to 2220 which they are not entitled. GSS-API credential creation is not 2221 intended to provide a "login to the network" function, as such a 2222 function would involve the creation of new credentials rather than 2223 merely acquiring a handle to existing credentials. Such functions, 2224 if required, should be defined in implementation-specific extensions 2225 to the API. 2227 If credential acquisition is time-consuming for a mechanism, the 2228 mechanism may choose to delay the actual acquisition until the 2229 credential is required (e.g., by GSSContext). Such mechanism- 2230 specific implementation decisions should be invisible to the calling 2231 application; thus, the query methods immediately following the 2232 creation of a credential object must return valid credential data, 2233 and may therefore incur the overhead of a deferred credential 2234 acquisition. 2236 Applications will create a credential object passing the desired 2237 parameters. The application can then use the query methods to obtain 2238 specific information about the instantiated credential object 2239 (equivalent to the gss_inquire routines). When the credential is no 2240 longer needed, the application should call the dispose (equivalent to 2241 gss_release_cred) method to release any resources held by the 2242 credential object and to destroy any cryptographically sensitive 2243 information. 2245 Classes implementing this interface also implement the Cloneable 2246 interface. This indicates that the class will support the clone() 2247 method that will allow the creation of duplicate credentials. This 2248 is useful when called just before the add() call to retain a copy of 2249 the original credential. 2251 6.3.1. Example Code 2253 This example code demonstrates the creation of a GSSCredential 2254 implementation for a specific entity, querying of its fields, and its 2255 release when it is no longer needed. 2257 2258 GSSManager mgr = GSSManager.getInstance(); 2260 // start by creating a name object for the entity 2261 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2263 // now acquire credentials for the entity 2264 GSSCredential cred = mgr.createCredential(name, 2265 GSSCredential.ACCEPT_ONLY); 2267 // display credential information - name, remaining lifetime, 2268 // and the mechanisms it has been acquired over 2269 print(cred.getName().toString()); 2270 print(cred.getRemainingLifetime()); 2272 Oid[] mechs = cred.getMechs(); 2273 if (mechs != null) { 2274 for (int i = 0; i < mechs.length; i++) 2275 print(mechs[i].toString()); 2276 } 2277 // release system resources held by the credential 2278 cred.dispose(); 2279 2281 6.3.2. Static Constants 2283 public static final int INITIATE_AND_ACCEPT 2285 Credential usage flag requesting that it be able to be used for both 2286 context initiation and acceptance. The value of this constant is 0. 2288 public static final int INITIATE_ONLY 2290 Credential usage flag requesting that it be able to be used for 2291 context initiation only. The value of this constant is 1. 2293 public static final int ACCEPT_ONLY 2295 Credential usage flag requesting that it be able to be used for 2296 context acceptance only. The value of this constant is 2. 2298 public static final int DEFAULT_LIFETIME 2300 A lifetime constant representing the default credential lifetime. 2301 The value of this constant is 0. 2303 public static final int INDEFINITE_LIFETIME 2305 A lifetime constant representing indefinite credential lifetime. The 2306 value of this constant is the maximum integer value in Java - 2307 Integer.MAX_VALUE. 2309 6.3.3. dispose 2311 public void dispose() throws GSSException 2313 Releases any sensitive information that the GSSCredential object may 2314 be containing. Applications should call this method as soon as the 2315 credential is no longer needed to minimize the time any sensitive 2316 information is maintained. 2318 6.3.4. getName 2320 public GSSName getName() throws GSSException 2322 Retrieves the name of the entity that the credential asserts. 2324 6.3.5. getName 2326 public GSSName getName(Oid mechOID) throws GSSException 2327 Retrieves a mechanism name of the entity that the credential asserts. 2328 Equivalent to calling canonicalize() on the name returned by section 2329 6.3.4. 2331 Parameters: 2333 mechOID The mechanism for which information should be 2334 returned. 2336 6.3.6. getRemainingLifetime 2338 public int getRemainingLifetime() throws GSSException 2340 Returns the remaining lifetime in seconds for a credential. The 2341 remaining lifetime is the minimum lifetime for any of the underlying 2342 credential mechanisms. A return value of 2343 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2344 not expire. A return value of 0 indicates that the credential is 2345 already expired. 2347 6.3.7. getRemainingInitLifetime 2349 public int getRemainingInitLifetime(Oid mech) throws GSSException 2351 Returns the remaining lifetime in seconds for the credential to 2352 remain capable of initiating security contexts under the specified 2353 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2354 indicates that the credential does not expire for context initiation. 2355 A return value of 0 indicates that the credential is already expired. 2357 Parameters: 2359 mechOID The mechanism for which information should be 2360 returned. 2362 6.3.8. getRemainingAcceptLifetime 2364 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2366 Returns the remaining lifetime in seconds for the credential to 2367 remain capable of accepting security contexts under the specified 2368 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2369 indicates that the credential does not expire for context acceptance. 2370 A return value of 0 indicates that the credential is already expired. 2372 Parameters: 2374 mechOID The mechanism for which information should be 2375 returned. 2377 6.3.9. getUsage 2379 public int getUsage() throws GSSException 2381 Returns the credential usage flag as a union over all mechanisms. 2382 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2383 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2385 6.3.10. getUsage 2387 public int getUsage(Oid mechOID) throws GSSException 2389 Returns the credential usage flag for the specified mechanism only. 2390 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2391 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2393 Parameters: 2395 mechOID The mechanism for which information should be 2396 returned. 2398 6.3.11. getMechs 2400 public Oid[] getMechs() throws GSSException 2402 Returns an array of mechanisms supported by this credential. 2404 6.3.12. add 2406 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2407 Oid mech, int usage) throws GSSException 2409 Adds a mechanism-specific credential-element to an existing 2410 credential. This method allows the construction of credentials one 2411 mechanism at a time. 2413 This routine is envisioned to be used mainly by context acceptors 2414 during the creation of acceptance credentials, which are to be used 2415 with a variety of clients using different security mechanisms. 2417 This routine adds the new credential element "in-place". To add the 2418 element in a new credential, first call clone() to obtain a copy of 2419 this credential, then call its add() method. 2421 Parameters: 2423 aName Name of the principal for whom this credential is 2424 to be acquired. Use "null" to specify the 2425 default principal. 2427 initLifetime The number of seconds that credentials should 2428 remain valid for initiating of security contexts. 2429 Use GSSCredential.INDEFINITE_LIFETIME to request 2430 that the credentials have the maximum permitted 2431 lifetime. Use GSSCredential.DEFAULT_LIFETIME to 2432 request default credential lifetime. 2434 acceptLifetime The number of seconds that credentials should 2435 remain valid for accepting of security contexts. 2437 Use GSSCredential.INDEFINITE_LIFETIME to request 2438 that the credentials 2439 have the maximum permitted lifetime. Use 2440 GSSCredential.DEFAULT_LIFETIME to request default 2441 credential lifetime. 2443 mech The mechanisms over which the credential is to be 2444 acquired. 2446 usage The intended usage for this credential object. 2447 The value of this parameter must be one of: 2449 GSSCredential.INITIATE_AND_ACCEPT(0), 2450 GSSCredential.INITIATE_ONLY(1), or 2451 GSSCredential.ACCEPT_ONLY(2) 2453 6.3.13. equals 2455 public boolean equals(Object another) 2457 Tests if this GSSCredential refers to the same entity as the supplied 2458 object. The two credentials must be acquired over the same 2459 mechanisms and must refer to the same principal. Returns "true" if 2460 the two GSSCredentials refer to the same entity; "false" otherwise. 2461 (Note that the Java language specification [JLS] requires that two 2462 objects that are equal according to the equals(Object) method must 2463 return the same integer result when the hashCode() method is called 2464 on them.) 2466 Parameters: 2468 another Another GSSCredential object for comparison. 2470 6.4. public interface GSSContext 2472 This interface encapsulates the GSS-API security context and provides 2473 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2474 available over the context. Security contexts are established 2475 between peers using locally acquired credentials. Multiple contexts 2476 may exist simultaneously between a pair of peers, using the same or 2477 different set of credentials. GSS-API functions in a manner 2478 independent of the underlying transport protocol and depends on its 2479 calling application to transport its tokens between peers. 2481 Before the context establishment phase is initiated, the context 2482 initiator may request specific characteristics desired of the 2483 established context. These can be set using the set methods. After 2484 the context is established, the caller can check the actual 2485 characteristic and services offered by the context using the query 2486 methods. 2488 The context establishment phase begins with the first call to the 2489 init method by the context initiator. During this phase, the 2490 initSecContext and acceptSecContext methods will produce GSS-API 2491 authentication tokens, which the calling application needs to send to 2492 its peer. If an error occurs at any point, an exception will get 2493 thrown and the code will start executing in a catch block where the 2494 exception may contain an output token that should be sent to the peer 2495 for debugging or informational purpose. If not, the normal flow of 2496 code continues and the application can make a call to the 2497 isEstablished() method. If this method returns "false" it indicates 2498 that a token is needed from its peer in order to continue the context 2499 establishment phase. A return value of "true" signals that the local 2500 end of the context is established. This may still require that a 2501 token be sent to the peer, if one is produced by GSS-API. During the 2502 context establishment phase, the isProtReady() method may be called 2503 to determine if the context can be used for the per-message 2504 operations. This allows applications to use per-message operations 2505 on contexts that aren't fully established. 2507 After the context has been established or the isProtReady() method 2508 returns "true", the query routines can be invoked to determine the 2509 actual characteristics and services of the established context. The 2510 application can also start using the per-message methods of wrap and 2511 getMIC to obtain cryptographic operations on application supplied 2512 data. 2514 When the context is no longer needed, the application should call 2515 dispose to release any system resources the context may be using. 2517 6.4.1. Example Code 2519 The example code presented below demonstrates the usage of the 2520 GSSContext interface for the initiating peer. Different operations 2521 on the GSSContext object are presented, including: object 2522 instantiation, setting of desired flags, context establishment, query 2523 of actual context flags, per-message operations on application data, 2524 and finally context deletion. 2526 2527 GSSManager mgr = GSSManager.getInstance(); 2529 // start by creating the name for a service entity 2530 GSSName targetName = mgr.createName("service@host", 2531 GSSName.NT_HOSTBASED_SERVICE); 2532 // create a context using default credentials for the above entity 2533 // and the implementation-specific default mechanism 2534 GSSContext context = mgr.createContext(targetName, 2535 null, /* default mechanism */ 2536 null, /* default credentials */ 2537 GSSContext.INDEFINITE_LIFETIME); 2539 // set desired context options - all others are "false" by default 2540 context.requestConf(true); 2541 context.requestMutualAuth(true); 2542 context.requestReplayDet(true); 2543 context.requestSequenceDet(true); 2545 // establish a context between peers - using byte arrays 2546 byte[]inTok = new byte[0]; 2548 try { 2549 do { 2550 byte[] outTok = context.initSecContext(inTok, 0, 2551 inTok.length); 2553 // send the token if present 2554 if (outTok != null) 2555 sendToken(outTok); 2557 // check if we should expect more tokens 2558 if (context.isEstablished()) 2559 break; 2561 // another token expected from peer 2562 inTok = readToken(); 2564 } while (true); 2566 } catch (GSSException e) { 2567 print("GSSAPI error: " + e.getMessage()); 2569 // If the exception contains an output token, 2570 // it should be sent to the acceptor. 2571 byte[] outTok = e.getOutputToken(); 2572 if (outTok != null) { 2573 sendToken(outTok); 2574 } 2576 return; 2577 } 2579 // display context information 2580 print("Remaining lifetime in seconds = " + context.getLifetime()); 2581 print("Context mechanism = " + context.getMech().toString()); 2582 print("Initiator = " + context.getSrcName().toString()); 2583 print("Acceptor = " + context.getTargName().toString()); 2585 if (context.getConfState()) 2586 print("Confidentiality security service available"); 2588 if (context.getIntegState()) 2589 print("Integrity security service available"); 2591 // perform wrap on an application-supplied message, appMsg, 2592 // using QOP = 0, and requesting privacy service 2593 byte[] appMsg ... 2595 MessageProp mProp = new MessageProp(0, true); 2597 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2599 if (mProp.getPrivacy()) 2600 print("Message protected with privacy."); 2602 sendToken(tok); 2604 // release the local end of the context 2605 context.dispose(); 2606 2608 6.4.2. Static Constants 2610 public static final int DEFAULT_LIFETIME 2612 A lifetime constant representing the default context lifetime. The 2613 value of this constant is 0. 2615 public static final int INDEFINITE_LIFETIME 2617 A lifetime constant representing indefinite context lifetime. The 2618 value of this constant is the maximum integer value in Java - 2619 Integer.MAX_VALUE. 2621 6.4.3. initSecContext 2623 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2624 throws GSSException 2626 Called by the context initiator to start the context creation 2627 process. This is equivalent to the stream-based method except that 2628 the token buffers are handled as byte arrays instead of using stream 2629 objects. This method may return an output token that the application 2630 will need to send to the peer for processing by the accept call. 2631 Typically, the application would do so by calling the flush() method 2632 on an OutputStream that encapsulates the connection between the two 2633 peers. The application can call isEstablished() to determine if the 2634 context establishment phase is complete for this peer. A return 2635 value of "false" from isEstablished() indicates that more tokens are 2636 expected to be supplied to the initSecContext() method. Note that it 2637 is possible that the initSecContext() method will return a token for 2638 the peer and isEstablished() will return "true" also. This indicates 2639 that the token needs to be sent to the peer, but the local end of the 2640 context is now fully established. 2642 Upon completion of the context establishment, the available context 2643 options may be queried through the get methods. 2645 A GSSException will be thrown if the call fails. Users should call 2646 its getOutputToken() method to find out if there is a token that can 2647 be sent to the acceptor to inform the reason for the error. 2649 Parameters: 2651 inputBuf Token generated by the peer. This parameter is 2652 ignored on the first call. 2654 offset The offset within the inputBuf where the token 2655 begins. 2657 len The length of the token within the inputBuf 2658 (starting at the offset). 2660 6.4.4. Example Code 2662 2663 // Create a new GSSContext implementation object. 2664 // GSSContext wrapper implements interface GSSContext. 2665 GSSContext context = mgr.createContext(...); 2667 byte[] inTok = new byte[0]; 2669 try { 2670 do { 2671 byte[] outTok = context.initSecContext(inTok, 0, 2672 inTok.length); 2674 // send the token if present 2675 if (outTok != null) 2676 sendToken(outTok); 2678 // check if we should expect more tokens 2679 if (context.isEstablished()) 2680 break; 2682 // another token expected from peer 2683 inTok = readToken(); 2684 } while (true); 2686 } catch (GSSException e) { 2687 print("GSSAPI error: " + e.getMessage()); 2689 // If the exception contains an output token, 2690 // it should be sent to the acceptor. 2691 byte[] outTok = e.getOutputToken(); 2692 if (outTok != null) { 2693 sendToken(outTok); 2694 } 2695 } 2696 2698 6.4.5. initSecContext 2700 public int initSecContext(InputStream inStream, 2701 OutputStream outStream) throws GSSException 2703 Called by the context initiator to start the context creation 2704 process. This is equivalent to the byte-array-based method. This 2705 method may write an output token to the outStream, which the 2706 application will need to send to the peer for processing by the 2707 accept call. Typically, the application would do so by calling the 2708 flush() method on an OutputStream that encapsulates the connection 2709 between the two peers. The application can call isEstablished() to 2710 determine if the context establishment phase is complete for this 2711 peer. A return value of "false" from isEstablished indicates that 2712 more tokens are expected to be supplied to the initSecContext method. 2713 Note that it is possible that the initSecContext() method will return 2714 a token for the peer and isEstablished() will return "true" also. 2715 This indicates that the token needs to be sent to the peer, but the 2716 local end of the context is now fully established. 2718 The GSS-API authentication tokens contain a definitive start and end. 2719 This method will attempt to read one of these tokens per invocation, 2720 and may block on the stream if only part of the token is available. 2722 Upon completion of the context establishment, the available context 2723 options may be queried through the get methods. 2725 A GSSException will be thrown if the call fails. Users should call 2726 its getOutputToken() method to find out if there is a token that can 2727 be sent to the acceptor to inform the reason for the error. 2729 Parameters: 2731 inStream Contains the token generated by the peer. This 2732 parameter is ignored on the first call. 2734 outStream Output stream where the output token will be 2735 written. During the final stage of context 2736 establishment, there may be no bytes written. 2738 6.4.6. Example Code 2740 This sample code merely demonstrates the token exchange during the 2741 context establishment phase. It is expected that most Java 2742 applications will use custom implementations of the Input and Output 2743 streams that encapsulate the communication routines. For instance, a 2744 simple read on the application InputStream, when called by the 2745 Context, might cause a token to be read from the peer, and a simple 2746 flush() on the application OutputStream might cause a previously 2747 written token to be transmitted to the peer. 2749 2750 // Create a new GSSContext implementation object. 2751 // GSSContext wrapper implements interface GSSContext. 2752 GSSContext context = mgr.createContext(...); 2753 // use standard java.io stream objects 2754 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2755 ByteArrayInputStream is = null; 2757 try { 2758 do { 2759 context.initSecContext(is, os); 2761 // send token if present 2762 if (os.size() > 0) 2763 sendToken(os); 2765 // check if we should expect more tokens 2766 if (context.isEstablished()) 2767 break; 2769 // another token expected from peer 2770 is = recvToken(); 2772 } while (true); 2774 } catch (GSSException e) { 2775 print("GSSAPI error: " + e.getMessage()); 2777 // If the exception contains an output token, 2778 // it should be sent to the acceptor. 2779 byte[] outTok = e.getOutputToken(); 2780 if (outTok != null) { 2781 sendToken(new ByteArrayOutputStream(outTok)); 2782 } 2783 } 2784 2786 6.4.7. acceptSecContext 2788 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2789 throws GSSException 2791 Called by the context acceptor upon receiving a token from the peer. 2792 This call is equivalent to the stream-based method except that the 2793 token buffers are handled as byte arrays instead of using stream 2794 objects. 2796 This method may return an output token that the application will need 2797 to send to the peer for further processing by the init call. 2799 The "null" return value indicates that no token needs to be sent to 2800 the peer. The application can call isEstablished() to determine if 2801 the context establishment phase is complete for this peer. A return 2802 value of "false" from isEstablished() indicates that more tokens are 2803 expected to be supplied to this method. 2805 Note that it is possible that acceptSecContext() will return a token 2806 for the peer and isEstablished() will return "true" also. This 2807 indicates that the token needs to be sent to the peer, but the local 2808 end of the context is now fully established. 2810 Upon completion of the context establishment, the available context 2811 options may be queried through the get methods. 2813 A GSSException will be thrown if the call fails. Users should call 2814 its getOutputToken() method to find out if there is a token that can 2815 be sent to the initiator to inform the reason for the error. 2817 Parameters: 2819 inTok Token generated by the peer. 2821 offset The offset within the inTok where the token 2822 begins. 2824 len The length of the token within the inTok 2825 (starting at the offset). 2827 6.4.8. Example Code 2828 2829 // acquire server credentials 2830 GSSCredential server = mgr.createCredential(...); 2832 // create acceptor GSS-API context from the default provider 2833 GSSContext context = mgr.createContext(server, null); 2835 try { 2836 do { 2837 byte[] inTok = readToken(); 2839 byte[] outTok = context.acceptSecContext(inTok, 0, 2840 inTok.length); 2842 // possibly send token to peer 2843 if (outTok != null) 2844 sendToken(outTok); 2846 // check if local context establishment is complete 2847 if (context.isEstablished()) 2848 break; 2849 } while (true); 2851 } catch (GSSException e) { 2852 print("GSS-API error: " + e.getMessage()); 2854 // If the exception contains an output token, 2855 // it should be sent to the initiator. 2856 byte[] outTok = e.getOutputToken(); 2857 if (outTok != null) { 2858 sendToken(outTok); 2859 } 2860 } 2861 2863 6.4.9. acceptSecContext 2865 public void acceptSecContext(InputStream inStream, 2866 OutputStream outStream) throws GSSException 2868 Called by the context acceptor upon receiving a token from the peer. 2869 This call is equivalent to the byte array method. It may write an 2870 output token to the outStream, which the application will need to 2871 send to the peer for processing by its initSecContext method. 2872 Typically, the application would do so by calling the flush() method 2873 on an OutputStream that encapsulates the connection between the two 2874 peers. The application can call isEstablished() to determine if the 2875 context establishment phase is complete for this peer. A return 2876 value of "false" from isEstablished() indicates that more tokens are 2877 expected to be supplied to this method. 2879 Note that it is possible that acceptSecContext() will return a token 2880 for the peer and isEstablished() will return "true" also. This 2881 indicates that the token needs to be sent to the peer, but the local 2882 end of the context is now fully established. 2884 The GSS-API authentication tokens contain a definitive start and end. 2885 This method will attempt to read one of these tokens per invocation, 2886 and may block on the stream if only part of the token is available. 2888 Upon completion of the context establishment, the available context 2889 options may be queried through the get methods. 2891 A GSSException will be thrown if the call fails. Users should call 2892 its getOutputToken() method to find out if there is a token that can 2893 be sent to the initiator to inform the reason for the error. 2895 Parameters: 2897 inStream Contains the token generated by the peer. 2899 outStream Output stream where the output token will be 2900 written. During the final stage of context 2901 establishment, there may be no bytes written. 2903 6.4.10. Example Code 2905 This sample code merely demonstrates the token exchange during the 2906 context establishment phase. It is expected that most Java 2907 applications will use custom implementations of the Input and Output 2908 streams that encapsulate the communication routines. For instance, a 2909 simple read on the application InputStream, when called by the 2910 Context, might cause a token to be read from the peer, and a simple 2911 flush() on the application OutputStream might cause a previously 2912 written token to be transmitted to the peer. 2914 2915 // acquire server credentials 2916 GSSCredential server = mgr.createCredential(...); 2918 // create acceptor GSS-API context from the default provider 2919 GSSContext context = mgr.createContext(server, null); 2921 // use standard java.io stream objects 2922 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2923 ByteArrayInputStream is = null; 2925 try { 2926 do { 2928 is = recvToken(); 2930 context.acceptSecContext(is, os); 2932 // possibly send token to peer 2933 if (os.size() > 0) 2934 sendToken(os); 2936 // check if local context establishment is complete 2937 if (context.isEstablished()) 2938 break; 2939 } while (true); 2941 } catch (GSSException e) { 2942 print("GSS-API error: " + e.getMessage()); 2944 // If the exception contains an output token, 2945 // it should be sent to the initiator. 2946 byte[] outTok = e.getOutputToken(); 2947 if (outTok != null) { 2948 sendToken(new ByteArrayOutputStream(outTok)); 2949 } 2950 } 2951 2953 6.4.11. isEstablished 2955 public boolean isEstablished() 2957 Used during context establishment to determine the state of the 2958 context. Returns "true" if this is a fully established context on 2959 the caller's side and no more tokens are needed from the peer. 2960 Should be called after a call to initSecContext() or 2961 acceptSecContext() when no GSSException is thrown. 2963 6.4.12. dispose 2965 public void dispose() throws GSSException 2967 Releases any system resources and cryptographic information stored in 2968 the context object. This will invalidate the context. 2970 6.4.13. getWrapSizeLimit 2972 public int getWrapSizeLimit(int qop, boolean confReq, 2973 int maxTokenSize) throws GSSException 2975 Returns the maximum message size that, if presented to the wrap 2976 method with the same confReq and qop parameters, will result in an 2977 output token containing no more than the maxTokenSize bytes. 2979 This call is intended for use by applications that communicate over 2980 protocols that impose a maximum message size. It enables the 2981 application to fragment messages prior to applying protection. 2983 GSS-API implementations are recommended but not required to detect 2984 invalid QOP values when getWrapSizeLimit is called. This routine 2985 guarantees only a maximum message size, not the availability of 2986 specific QOP values for message protection. 2988 Successful completion of this call does not guarantee that wrap will 2989 be able to protect a message of the computed length, since this 2990 ability may depend on the availability of system resources at the 2991 time that wrap is called. However, if the implementation itself 2992 imposes an upper limit on the length of messages that may be 2993 processed by wrap, the implementation should not return a value that 2994 is greater than this length. 2996 Parameters: 2998 qop Indicates the level of protection wrap will be 2999 asked to provide. 3001 confReq Indicates if wrap will be asked to provide 3002 privacy service. 3004 maxTokenSize The desired maximum size of the token emitted by 3005 wrap. 3007 6.4.14. wrap 3009 public byte[] wrap(byte[] inBuf, int offset, int len, 3010 MessageProp msgProp) throws GSSException 3012 Applies per-message security services over the established security 3013 context. The method will return a token with a cryptographic MIC and 3014 may optionally encrypt the specified inBuf. This method is 3015 equivalent in functionality to its stream counterpart. The returned 3016 byte array will contain both the MIC and the message. 3018 The MessageProp object is instantiated by the application and used to 3019 specify a QOP value that selects cryptographic algorithms, and a 3020 privacy service to optionally encrypt the message. The underlying 3021 mechanism that is used in the call may not be able to provide the 3022 privacy service. It sets the actual privacy service that it does 3023 provide in this MessageProp object, which the caller should then 3024 query upon return. If the mechanism is not able to provide the 3025 requested QOP, it throws a GSSException with the BAD_QOP code. 3027 Since some application-level protocols may wish to use tokens emitted 3028 by wrap to provide "secure framing", implementations should support 3029 the wrapping of zero-length messages. 3031 The application will be responsible for sending the token to the 3032 peer. 3034 Parameters: 3036 inBuf Application data to be protected. 3038 offset The offset within the inBuf where the data 3039 begins. 3041 len The length of the data within the inBuf (starting 3042 at the offset). 3044 msgProp Instance of MessageProp that is used by the 3045 application to set the desired QOP and privacy 3046 state. Set the desired QOP to 0 to request the 3047 default QOP. Upon return from this method, this 3048 object will contain the actual privacy state that 3049 was applied to the message by the underlying 3050 mechanism. 3052 6.4.15. wrap 3054 public void wrap(InputStream inStream, OutputStream outStream, 3055 MessageProp msgProp) throws GSSException 3057 Allows to apply per-message security services over the established 3058 security context. The method will produce a token with a 3059 cryptographic MIC and may optionally encrypt the message in inStream. 3060 The outStream will contain both the MIC and the message. 3062 The MessageProp object is instantiated by the application and used to 3063 specify a QOP value that selects cryptographic algorithms, and a 3064 privacy service to optionally encrypt the message. The underlying 3065 mechanism that is used in the call may not be able to provide the 3066 privacy service. It sets the actual privacy service that it does 3067 provide in this MessageProp object, which the caller should then 3068 query upon return. If the mechanism is not able to provide the 3069 requested QOP, it throws a GSSException with the BAD_QOP code. 3071 Since some application-level protocols may wish to use tokens emitted 3072 by wrap to provide "secure framing", implementations should support 3073 the wrapping of zero-length messages. 3075 The application will be responsible for sending the token to the 3076 peer. 3078 Parameters: 3080 inStream Input stream containing the application data to 3081 be protected. 3083 outStream The output stream to which to write the protected 3084 message. The application is responsible for 3085 sending this to the other peer for processing in 3086 its unwrap method. 3088 msgProp Instance of MessageProp that is used by the 3089 application to set the desired QOP and privacy 3090 state. Set the desired QOP to 0 to request the 3091 default QOP. Upon return from this method, this 3092 object will contain the actual privacy state that 3093 was applied to the message by the underlying 3094 mechanism. 3096 6.4.16. unwrap 3098 public byte[] unwrap(byte[] inBuf, int offset, int len, 3099 MessageProp msgProp) throws GSSException 3101 Used by the peer application to process tokens generated with the 3102 wrap call. This call is equal in functionality to its stream 3103 counterpart. The method will return the message supplied in the peer 3104 application to the wrap call, verifying the embedded MIC. 3106 The MessageProp object is instantiated by the application and is used 3107 by the underlying mechanism to return information to the caller such 3108 as the QOP, whether confidentiality was applied to the message, and 3109 other supplementary message state information. 3111 Since some application-level protocols may wish to use tokens emitted 3112 by wrap to provide "secure framing", implementations should support 3113 the wrapping and unwrapping of zero-length messages. 3115 Parameters: 3117 inBuf GSS-API wrap token received from peer. 3119 offset The offset within the inBuf where the token 3120 begins. 3122 len The length of the token within the inBuf 3123 (starting at the offset). 3125 msgProp Upon return from the method, this object will 3126 contain the applied QOP, the privacy state of the 3127 message, and supplementary information, described 3128 in section 4.12.3, stating whether the token was 3129 a duplicate, old, out of sequence, or arriving 3130 after a gap. 3132 6.4.17. unwrap 3134 public void unwrap(InputStream inStream, OutputStream outStream, 3135 MessageProp msgProp) throws GSSException 3137 Used by the peer application to process tokens generated with the 3138 wrap call. This call is equal in functionality to its byte array 3139 counterpart. It will produce the message supplied in the peer 3140 application to the wrap call, verifying the embedded MIC. 3142 The MessageProp object is instantiated by the application and is used 3143 by the underlying mechanism to return information to the caller such 3144 as the QOP, whether confidentiality was applied to the message, and 3145 other supplementary message state information. 3147 Since some application-level protocols may wish to use tokens emitted 3148 by wrap to provide "secure framing", implementations should support 3149 the wrapping and unwrapping of zero-length messages. 3151 Parameters: 3153 inStream Input stream containing the GSS-API wrap token 3154 received from the peer. 3156 outStream The output stream to which to write the 3157 application message. 3159 msgProp Upon return from the method, this object will 3160 contain the applied QOP, the privacy state of the 3161 message, and supplementary information, described 3162 in section 4.12.3, stating whether the token was 3163 a duplicate, old, out of sequence, or arriving 3164 after a gap. 3166 6.4.18. getMIC 3168 public byte[] getMIC(byte[] inMsg, int offset, int len, 3169 MessageProp msgProp) throws GSSException 3171 Returns a token containing a cryptographic MIC for the supplied 3172 message for transfer to the peer application. Unlike wrap, which 3173 encapsulates the user message in the returned token, only the message 3174 MIC is returned in the output token. This method is identical in 3175 functionality to its stream counterpart. 3177 Note that privacy can only be applied through the wrap call. 3179 Since some application-level protocols may wish to use tokens emitted 3180 by getMIC to provide "secure framing", implementations should support 3181 derivation of MICs from zero-length messages. 3183 Parameters: 3185 inMsg Message over which to generate MIC. 3187 offset The offset within the inMsg where the token 3188 begins. 3190 len The length of the token within the inMsg 3191 (starting at the offset). 3193 msgProp Instance of MessageProp that is used by the 3194 application to set the desired QOP. Set the 3195 desired QOP to 0 in msgProp to request the 3196 default QOP. Alternatively, pass in "null" for 3197 msgProp to request default QOP. 3199 6.4.19. getMIC 3201 public void getMIC(InputStream inStream, OutputStream outStream, 3202 MessageProp msgProp) throws GSSException 3204 Produces a token containing a cryptographic MIC for the supplied 3205 message, for transfer to the peer application. Unlike wrap, which 3206 encapsulates the user message in the returned token, only the message 3207 MIC is produced in the output token. This method is identical in 3208 functionality to its byte array counterpart. 3210 Note that privacy can only be applied through the wrap call. 3212 Since some application-level protocols may wish to use tokens emitted 3213 by getMIC to provide "secure framing", implementations should support 3214 derivation of MICs from zero-length messages. 3216 Parameters: 3218 inStream Input stream containing the message over which to 3219 generate MIC. 3221 outStream Output stream to which to write the GSS-API 3222 output token. 3224 msgProp Instance of MessageProp that is used by the 3225 application to set the desired QOP. Set the 3226 desired QOP to 0 in msgProp to request the 3227 default QOP. Alternatively, pass in "null" for 3228 msgProp to request default QOP. 3230 6.4.20. verifyMIC 3232 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 3233 byte[] inMsg, int msgOffset, int msgLen, 3234 MessageProp msgProp) throws GSSException 3236 Verifies the cryptographic MIC, contained in the token parameter, 3237 over the supplied message. This method is equivalent in 3238 functionality to its stream counterpart. 3240 The MessageProp object is instantiated by the application and is used 3241 by the underlying mechanism to return information to the caller such 3242 as the QOP indicating the strength of protection that was applied to 3243 the message and other supplementary message state information. 3245 Since some application-level protocols may wish to use tokens emitted 3246 by getMIC to provide "secure framing", implementations should support 3247 the calculation and verification of MICs over zero-length messages. 3249 Parameters: 3251 inTok Token generated by peer's getMIC method. 3253 tokOffset The offset within the inTok where the token 3254 begins. 3256 tokLen The length of the token within the inTok 3257 (starting at the offset). 3259 inMsg Application message over which to verify the 3260 cryptographic MIC. 3262 msgOffset The offset within the inMsg where the message 3263 begins. 3265 msgLen The length of the message within the inMsg 3266 (starting at the offset). 3268 msgProp Upon return from the method, this object will 3269 contain the applied QOP and supplementary 3270 information, described in section 4.12.3, stating 3271 whether the token was a duplicate, old, out of 3272 sequence, or arriving after a gap. The 3273 confidentiality state will be set to "false". 3275 6.4.21. verifyMIC 3277 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3278 MessageProp msgProp) throws GSSException 3280 Verifies the cryptographic MIC, contained in the token parameter, 3281 over the supplied message. This method is equivalent in 3282 functionality to its byte array counterpart. 3284 The MessageProp object is instantiated by the application and is used 3285 by the underlying mechanism to return information to the caller such 3286 as the QOP indicating the strength of protection that was applied to 3287 the message and other supplementary message state information. 3289 Since some application-level protocols may wish to use tokens emitted 3290 by getMIC to provide "secure framing", implementations should support 3291 the calculation and verification of MICs over zero-length messages. 3293 Parameters: 3295 tokStream Input stream containing the token generated by 3296 the peer's getMIC method. 3298 msgStream Input stream containing the application message 3299 over which to verify the cryptographic MIC. 3301 msgProp Upon return from the method, this object will 3302 contain the applied QOP and supplementary 3303 information, described in section 4.12.3, stating 3304 whether the token was a duplicate, old, out of 3305 sequence, or arriving after a gap. The 3306 confidentiality state will be set to "false". 3308 6.4.22. export 3310 public byte[] export() throws GSSException 3312 Provided to support the sharing of work between multiple processes. 3313 This routine will typically be used by the context acceptor, in an 3314 application where a single process receives incoming connection 3315 requests and accepts security contexts over them, then passes the 3316 established context to one or more other processes for message 3317 exchange. 3319 This method deactivates the security context and creates an inter- 3320 process token which, when passed to the byte array constructor of the 3321 GSSContext interface in another process, will re-activate the context 3322 in the second process. Only a single instantiation of a given 3323 context may be active at any one time; a subsequent attempt by a 3324 context exporter to access the exported security context will fail. 3326 The implementation may constrain the set of processes by which the 3327 inter-process token may be imported, either as a function of local 3328 security policy, or as a result of implementation decisions. For 3329 example, some implementations may constrain contexts to be passed 3330 only between processes that run under the same account, or which are 3331 part of the same process group. 3333 The inter-process token may contain security-sensitive information 3334 (for example, cryptographic keys). While mechanisms are encouraged 3335 to either avoid placing such sensitive information within inter- 3336 process tokens or to encrypt the token before returning it to the 3337 application, in a typical GSS-API implementation, this may not be 3338 possible. Thus, the application must take care to protect the inter- 3339 process token, and ensure that any process to which the token is 3340 transferred is trustworthy. 3342 6.4.23. requestMutualAuth 3344 public void requestMutualAuth(boolean state) throws GSSException 3346 Sets the request state of the mutual authentication flag for the 3347 context. This method is only valid before the context creation 3348 process begins and only for the initiator. 3350 Parameters: 3352 state Boolean representing if mutual authentication 3353 should be requested during context establishment. 3355 6.4.24. requestReplayDet 3357 public void requestReplayDet(boolean state) throws GSSException 3359 Sets the request state of the replay detection service for the 3360 context. This method is only valid before the context creation 3361 process begins and only for the initiator. 3363 Parameters: 3365 state Boolean representing if replay detection is 3366 desired over the established context. 3368 6.4.25. requestSequenceDet 3370 public void requestSequenceDet(boolean state) throws GSSException 3372 Sets the request state for the sequence checking service of the 3373 context. This method is only valid before the context creation 3374 process begins and only for the initiator. 3376 Parameters: 3378 state Boolean representing if sequence detection is 3379 desired over the established context. 3381 6.4.26. requestCredDeleg 3383 public void requestCredDeleg(boolean state) throws GSSException 3385 Sets the request state for the credential delegation flag for the 3386 context. This method is only valid before the context creation 3387 process begins and only for the initiator. 3389 Parameters: 3391 state Boolean representing if credential delegation is 3392 desired. 3394 6.4.27. requestAnonymity 3396 public void requestAnonymity(boolean state) throws GSSException 3398 Requests anonymous support over the context. This method is only 3399 valid before the context creation process begins and only for the 3400 initiator. 3402 Parameters: 3404 state Boolean representing if anonymity support is 3405 requested. 3407 6.4.28. requestConf 3409 public void requestConf(boolean state) throws GSSException 3411 Requests that confidentiality service be available over the context. 3412 This method is only valid before the context creation process begins 3413 and only for the initiator. 3415 Parameters: 3417 state Boolean indicating if confidentiality services 3418 are to be requested for the context. 3420 6.4.29. requestInteg 3422 public void requestInteg(boolean state) throws GSSException 3424 Requests that integrity services be available over the context. This 3425 method is only valid before the context creation process begins and 3426 only for the initiator. 3428 Parameters: 3430 state Boolean indicating if integrity services are to 3431 be requested for the context. 3433 6.4.30. requestLifetime 3435 public void requestLifetime(int lifetime) throws GSSException 3437 Sets the desired lifetime for the context in seconds. This method is 3438 only valid before the context creation process begins and only for 3439 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 3440 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 3441 lifetime. 3443 Parameters: 3445 lifetime The desired context lifetime in seconds. 3447 6.4.31. setChannelBinding 3449 public void setChannelBinding(ChannelBinding cb) throws GSSException 3451 Sets the channel bindings to be used during context establishment. 3452 This method is only valid before the context creation process begins. 3454 Parameters: 3456 cb Channel bindings to be used. 3458 6.4.32. getCredDelegState 3460 public boolean getCredDelegState() 3462 Returns the state of the delegated credentials for the context. When 3463 issued before context establishment is completed or when the 3464 isProtReady method returns "false", it returns the desired state; 3465 otherwise, it will indicate the actual state over the established 3466 context. 3468 6.4.33. getMutualAuthState 3470 public boolean getMutualAuthState() 3472 Returns the state of the mutual authentication option for the 3473 context. When issued before context establishment completes or when 3474 the isProtReady method returns "false", it returns the desired state; 3475 otherwise, it will indicate the actual state over the established 3476 context. 3478 6.4.34. getReplayDetState 3480 public boolean getReplayDetState() 3482 Returns the state of the replay detection option for the context. 3483 When issued before context establishment completes or when the 3484 isProtReady method returns "false", it returns the desired state; 3485 otherwise, it will indicate the actual state over the established 3486 context. 3488 6.4.35. getSequenceDetState 3490 public boolean getSequenceDetState() 3492 Returns the state of the sequence detection option for the context. 3493 When issued before context establishment completes or when the 3494 isProtReady method returns "false", it returns the desired state; 3495 otherwise, it will indicate the actual state over the established 3496 context. 3498 6.4.36. getAnonymityState 3500 public boolean getAnonymityState() 3502 Returns "true" if this is an anonymous context. When issued before 3503 context establishment completes or when the isProtReady method 3504 returns "false", it returns the desired state; otherwise, it will 3505 indicate the actual state over the established context. 3507 6.4.37. isTransferable 3509 public boolean isTransferable() throws GSSException 3511 Returns "true" if the context is transferable to other processes 3512 through the use of the export method. This call is only valid on 3513 fully established contexts. 3515 6.4.38. isProtReady 3517 public boolean isProtReady() 3519 Returns "true" if the per-message operations can be applied over the 3520 context. Some mechanisms may allow the usage of per-message 3521 operations before the context is fully established. This will also 3522 indicate that the get methods will return actual context state 3523 characteristics instead of the desired ones. 3525 6.4.39. getConfState 3527 public boolean getConfState() 3529 Returns the confidentiality service state over the context. When 3530 issued before context establishment completes or when the isProtReady 3531 method returns "false", it returns the desired state; otherwise, it 3532 will indicate the actual state over the established context. 3534 6.4.40. getIntegState 3536 public boolean getIntegState() 3538 Returns the integrity service state over the context. When issued 3539 before context establishment completes or when the isProtReady method 3540 returns "false", it returns the desired state; otherwise, it will 3541 indicate the actual state over the established context. 3543 6.4.41. getLifetime 3545 public int getLifetime() 3547 Returns the context lifetime in seconds. When issued before context 3548 establishment completes or when the isProtReady method returns 3549 "false", it returns the desired lifetime; otherwise, it will indicate 3550 the remaining lifetime for the context. 3552 6.4.42. getSrcName 3554 public GSSName getSrcName() throws GSSException 3556 Returns the name of the context initiator. This call is valid only 3557 after the context is fully established or the isProtReady method 3558 returns "true". It is guaranteed to return an MN. 3560 6.4.43. getTargName 3562 public GSSName getTargName() throws GSSException 3564 Returns the name of the context target (acceptor). This call is 3565 valid only after the context is fully established or the isProtReady 3566 method returns "true". It is guaranteed to return an MN. 3568 6.4.44. getMech 3570 public Oid getMech() throws GSSException 3571 Returns the mechanism oid for this context. This method may be 3572 called before the context is fully established, but the mechanism 3573 returned may change on successive calls in negotiated mechanism case. 3575 6.4.45. getDelegCred 3577 public GSSCredential getDelegCred() throws GSSException 3579 Returns the delegated credential object on the acceptor's side. To 3580 check for availability of delegated credentials call 3581 getDelegCredState. This call is only valid on fully established 3582 contexts. 3584 6.4.46. isInitiator 3586 public boolean isInitiator() throws GSSException 3588 Returns "true" if this is the initiator of the context. This call is 3589 only valid after the context creation process has started. 3591 6.5. public class MessageProp 3593 This is a utility class used within the per-message GSSContext 3594 methods to convey per-message properties. 3596 When used with the GSSContext interface's wrap and getMIC methods, an 3597 instance of this class is used to indicate the desired QOP and to 3598 request if confidentiality services are to be applied to caller 3599 supplied data (wrap only). To request default QOP, the value of 0 3600 should be used for QOP. 3602 When used with the unwrap and verifyMIC methods of the GSSContext 3603 interface, an instance of this class will be used to indicate the 3604 applied QOP and confidentiality services over the supplied message. 3605 In the case of verifyMIC, the confidentiality state will always be 3606 "false". Upon return from these methods, this object will also 3607 contain any supplementary status values applicable to the processed 3608 token. The supplementary status values can indicate old tokens, out 3609 of sequence tokens, gap tokens, or duplicate tokens. 3611 6.5.1. Constructors 3613 public MessageProp(boolean privState) 3615 Constructor that sets QOP to 0 indicating that the default QOP is 3616 requested. 3618 Parameters: 3620 privState The desired privacy state. "true" for privacy and 3621 "false" for integrity only. 3623 public MessageProp(int qop, boolean privState) 3625 Constructor that sets the values for the qop and privacy state. 3627 Parameters: 3629 qop The desired QOP. Use 0 to request a default QOP. 3631 privState The desired privacy state. "true" for privacy and 3632 "false" for integrity only. 3634 6.5.2. getQOP 3636 public int getQOP() 3638 Retrieves the QOP value. 3640 6.5.3. getPrivacy 3642 public boolean getPrivacy() 3644 Retrieves the privacy state. 3646 6.5.4. getMinorStatus 3648 public int getMinorStatus() 3650 Retrieves the minor status that the underlying mechanism might have 3651 set. 3653 6.5.5. getMinorString 3655 public String getMinorString() 3657 Returns a string explaining the mechanism-specific error code. "null" 3658 will be returned when no mechanism error code has been set. 3660 6.5.6. setQOP 3662 public void setQOP(int qopVal) 3664 Sets the QOP value. 3666 Parameters: 3668 qopVal The QOP value to be set. Use 0 to request a 3669 default QOP value. 3671 6.5.7. setPrivacy 3673 public void setPrivacy(boolean privState) 3675 Sets the privacy state. 3677 Parameters: 3679 privState The privacy state to set. 3681 6.5.8. isDuplicateToken 3683 public boolean isDuplicateToken() 3685 Returns "true" if this is a duplicate of an earlier token. 3687 6.5.9. isOldToken 3689 public boolean isOldToken() 3691 Returns "true" if the token's validity period has expired. 3693 6.5.10. isUnseqToken 3695 public boolean isUnseqToken() 3697 Returns "true" if a later token has already been processed. 3699 6.5.11. isGapToken 3701 public boolean isGapToken() 3703 Returns "true" if an expected per-message token was not received. 3705 6.5.12. setSupplementaryStates 3707 public void setSupplementaryStates(boolean duplicate, 3708 boolean old, boolean unseq, boolean gap, 3709 int minorStatus, String minorString) 3711 This method sets the state for the supplementary information flags 3712 and the minor status in MessageProp. It is not used by the 3713 application but by the GSS implementation to return this information 3714 to the caller of a per-message context method. 3716 Parameters: 3718 duplicate "true" if the token was a duplicate of an earlier 3719 token; otherwise, "false". 3721 old "true" if the token's validity period has 3722 expired; otherwise, "false". 3724 unseq "true" if a later token has already been 3725 processed; otherwise, "false". 3727 gap "true" if one or more predecessor tokens have not 3728 yet been successfully processed; otherwise, 3729 "false". 3731 minorStatus The integer minor status code that the underlying 3732 mechanism wants to set. 3734 minorString The textual representation of the minorStatus 3735 value. 3737 6.6. public class ChannelBinding 3739 The GSS-API accommodates the concept of caller-provided channel 3740 binding information. Channel bindings are used to strengthen the 3741 quality with which peer entity authentication is provided during 3742 context establishment. They enable the GSS-API callers to bind the 3743 establishment of the security context to relevant characteristics 3744 like addresses or to application-specific data. 3746 The caller initiating the security context must determine the 3747 appropriate channel binding values to set in the GSSContext object. 3748 The acceptor must provide an identical binding in order to validate 3749 that received tokens possess correct channel-related characteristics. 3751 Use of channel bindings is optional in GSS-API. Since channel- 3752 binding information may be transmitted in context establishment 3753 tokens, applications should therefore not use confidential data as 3754 channel-binding components. 3756 6.6.1. Constructors 3758 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3759 byte[] appData) 3761 Create a ChannelBinding object with user-supplied address information 3762 and data. "null" values can be used for any fields that the 3763 application does not want to specify. 3765 Parameters: 3767 initAddr The address of the context initiator. "null" 3768 value can be supplied to indicate that the 3769 application does not want to set this value. 3771 acceptAddr The address of the context acceptor. "null" value 3772 can be supplied to indicate that the application 3773 does not want to set this value. 3775 appData Application-supplied data to be used as part of 3776 the channel bindings. "null" value can be 3777 supplied to indicate that the application does 3778 not want to set this value. 3780 public ChannelBinding(byte[] appData) 3782 Creates a ChannelBinding object without any addressing information. 3784 Parameters: 3786 appData Application supplied data to be used as part of 3787 the channel bindings. 3789 6.6.2. getInitiatorAddress 3791 public InetAddress getInitiatorAddress() 3793 Returns the initiator's address for this channel binding. "null" is 3794 returned if the address has not been set. 3796 6.6.3. getAcceptorAddress 3798 public InetAddress getAcceptorAddress() 3800 Returns the acceptor's address for this channel binding. "null" is 3801 returned if the address has not been set. 3803 6.6.4. getApplicationData 3805 public byte[] getApplicationData() 3807 Returns application data being used as part of the ChannelBinding. 3808 "null" is returned if no application data has been specified for the 3809 channel binding. 3811 6.6.5. equals 3813 public boolean equals(Object obj) 3815 Returns "true" if two channel bindings match. (Note that the Java 3816 language specification requires that two objects that are equal 3817 according to the equals(Object) method must return the same integer 3818 result when the hashCode() method is called on them.) 3820 Parameters: 3822 obj Another channel binding with which to compare. 3824 6.7. public class Oid 3826 This class represents Universal Object Identifiers (Oids) and their 3827 associated operations. 3829 Oids are hierarchically globally interpretable identifiers used 3830 within the GSS-API framework to identify mechanisms and name formats. 3832 The structure and encoding of Oids is defined in ISOIEC-8824 and 3833 ISOIEC-8825. For example, the Oid representation of the Kerberos v5 3834 mechanism is "1.2.840.113554.1.2.2". 3836 The GSSName name class contains public static Oid objects 3837 representing the standard name types defined in GSS-API. 3839 6.7.1. Constructors 3841 public Oid(String strOid) throws GSSException 3843 Creates an Oid object from a string representation of its integer 3844 components (e.g., "1.2.840.113554.1.2.2"). 3846 Parameters: 3848 strOid The string representation for the oid. 3850 public Oid(InputStream derOid) throws GSSException 3852 Creates an Oid object from its DER encoding. This refers to the full 3853 encoding including tag and length. The structure and encoding of 3854 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3855 identical in functionality to its byte array counterpart. 3857 Parameters: 3859 derOid Stream containing the DER-encoded oid. 3861 public Oid(byte[] DEROid) throws GSSException 3863 Creates an Oid object from its DER encoding. This refers to the full 3864 encoding including tag and length. The structure and encoding of 3865 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3866 identical in functionality to its byte array counterpart. 3868 Parameters: 3870 derOid Byte array storing a DER-encoded oid. 3872 6.7.2. toString 3874 public String toString() 3876 Returns a string representation of the oid's integer components in 3877 dot separated notation (e.g., "1.2.840.113554.1.2.2"). 3879 6.7.3. equals 3881 public boolean equals(Object Obj) 3883 Returns "true" if the two Oid objects represent the same oid value. 3884 (Note that the Java language specification [JLS] requires that two 3885 objects that are equal according to the equals(Object) method must 3886 return the same integer result when the hashCode() method is called 3887 on them.) 3889 Parameters: 3891 obj Another Oid object with which to compare. 3893 6.7.4. getDER 3895 public byte[] getDER() 3897 Returns the full ASN.1 DER encoding for this oid object, which 3898 includes the tag and length. 3900 6.7.5. containedIn 3902 public boolean containedIn(Oid[] oids) 3904 A utility method to test if an Oid object is contained within the 3905 supplied Oid object array. 3907 Parameters: 3909 oids An array of oids to search. 3911 6.8. public class GSSException extends Exception 3913 This exception is thrown whenever a fatal GSS-API error occurs 3914 including mechanism-specific errors. It may contain both, the major 3915 and minor, GSS-API status codes. The mechanism implementors are 3916 responsible for setting appropriate minor status codes when throwing 3917 this exception. Aside from delivering the numeric error code(s) to 3918 the caller, this class performs the mapping from their numeric values 3919 to textual representations. This exception may also include an 3920 output token that should be sent to the peer. For example, when an 3921 initSecContext call fails due to a fatal error, the mechanism may 3922 define an error token that should be sent to the peer for debugging 3923 or informational purpose. All Java GSS-API methods are declared 3924 throwing this exception. 3926 All implementations are encouraged to use the Java 3927 internationalization techniques to provide local translations of the 3928 message strings. 3930 6.8.1. Static Constants 3932 All valid major GSS-API error code values are declared as constants 3933 in this class. 3935 public static final int BAD_BINDINGS 3937 Channel bindings mismatch error. The value of this constant is 1. 3939 public static final int BAD_MECH 3941 Unsupported mechanism requested error. The value of this constant is 3942 2. 3944 public static final int BAD_NAME 3946 Invalid name provided error. The value of this constant is 3. 3948 public static final int BAD_NAMETYPE 3950 Name of unsupported type provided error. The value of this constant 3951 is 4. 3953 public static final int BAD_STATUS 3954 Invalid status code error - this is the default status value. The 3955 value of this constant is 5. 3957 public static final int BAD_MIC 3959 Token had invalid integrity check error. The value of this constant 3960 is 6. 3962 public static final int CONTEXT_EXPIRED 3964 Specified security context expired error. The value of this constant 3965 is 7. 3967 public static final int CREDENTIALS_EXPIRED 3969 Expired credentials detected error. The value of this constant is 8. 3971 public static final int DEFECTIVE_CREDENTIAL 3973 Defective credential error. The value of this constant is 9. 3975 public static final int DEFECTIVE_TOKEN 3977 Defective token error. The value of this constant is 10. 3979 public static final int FAILURE 3981 General failure, unspecified at GSS-API level. The value of this 3982 constant is 11. 3984 public static final int NO_CONTEXT 3986 Invalid security context error. The value of this constant is 12. 3988 public static final int NO_CRED 3990 Invalid credentials error. The value of this constant is 13. 3992 public static final int BAD_QOP 3994 Unsupported QOP value error. The value of this constant is 14. 3996 public static final int UNAUTHORIZED 3998 Operation unauthorized error. The value of this constant is 15. 4000 public static final int UNAVAILABLE 4001 Operation unavailable error. The value of this constant is 16. 4003 public static final int DUPLICATE_ELEMENT 4005 Duplicate credential element requested error. The value of this 4006 constant is 17. 4008 public static final int NAME_NOT_MN 4010 Name contains multi-mechanism elements error. The value of this 4011 constant is 18. 4013 public static final int DUPLICATE_TOKEN 4015 The token was a duplicate of an earlier token. This is contained in 4016 an exception only when detected during context establishment, in 4017 which case it is considered a fatal error. (Non-fatal supplementary 4018 codes are indicated via the MessageProp object.) The value of this 4019 constant is 19. 4021 public static final int OLD_TOKEN 4023 The token's validity period has expired. This is contained in an 4024 exception only when detected during context establishment, in which 4025 case it is considered a fatal error. (Non-fatal supplementary codes 4026 are indicated via the MessageProp object.) The value of this 4027 constant is 20. 4029 public static final int UNSEQ_TOKEN 4031 A later token has already been processed. This is contained in an 4032 exception only when detected during context establishment, in which 4033 case it is considered a fatal error. (Non-fatal supplementary codes 4034 are indicated via the MessageProp object.) The value of this 4035 constant is 21. 4037 public static final int GAP_TOKEN 4039 An expected per-message token was not received. This is contained in 4040 an exception only when detected during context establishment, in 4041 which case it is considered a fatal error. (Non-fatal supplementary 4042 codes are indicated via the MessageProp object.) The value of this 4043 constant is 22. 4045 6.8.2. Constructors 4047 public GSSException(int majorCode) 4049 Creates a GSSException object with a specified major code. 4051 Calling this constructor is equivalent to calling 4052 GSSException(majorCode, 0, null, null). 4054 public GSSException(int majorCode, int minorCode, String minorString) 4056 Creates a GSSException object with the specified major code, minor 4057 code, and minor code textual explanation. This constructor is to be 4058 used when the exception is originating from the security mechanism. 4059 It allows to specify the GSS code and the mechanism code. 4061 Calling this constructor is equivalent to calling 4062 GSSException(majorCode, minorCode, minorString, null). 4064 public GSSException(int majorCode, String majorString, 4065 int minorCode, String minorString, 4066 byte[] outputToken) 4068 Creates a GSSException object with the specified major code, major 4069 code textual explanation, minor code, minor code textual explanation, 4070 and an output token. This is a general-purpose constructor that can 4071 be used to create any type of GSSException. 4073 Parameters: 4075 majorCode The GSS error code causing this exception to be 4076 thrown. 4078 majorString The textual explanation of the GSS error code. 4079 If null is provided, a default explanation that 4080 matches the majorCode will be set. 4082 minorCode The mechanism error code causing this exception 4083 to be thrown. Can be 0 if no mechanism error 4084 code is available. 4086 minorString The textual explanation of the mechanism error 4087 code. Can be null if no textual explanation is 4088 available. 4090 outputToken The output token that should be sent to the peer. 4091 Can be null if no such token is available. It 4092 must not be an empty array. When provided, the 4093 array will be cloned to protect against 4094 subsequent modifications. 4096 6.8.3. getMajor 4098 public int getMajor() 4100 Returns the major code representing the GSS error code that caused 4101 this exception to be thrown. 4103 6.8.4. getMinor 4105 public int getMinor() 4107 Returns the mechanism error code that caused this exception. The 4108 minor code is set by the underlying mechanism. Value of 0 indicates 4109 that mechanism error code is not set. 4111 6.8.5. getMajorString 4113 public String getMajorString() 4115 Returns a string explaining the GSS major error code causing this 4116 exception to be thrown. 4118 6.8.6. getMinorString 4120 public String getMinorString() 4122 Returns a string explaining the mechanism-specific error code. "null" 4123 will be returned when no string explaining the mechanism error code 4124 has been set. 4126 6.8.7. getOutputToken 4128 public byte[] getOutputToken 4130 Returns the output token in a new byte array. 4132 If the method (For example, GSSContext#initSecContext) that throws 4133 this GSSException needs to generate an output token that should be 4134 sent to the peer, that token will be stored in this GSSException and 4135 can be retrieved with this method. 4137 The return value must be null if no such token is generated. It must 4138 not be an empty byte array. 4140 6.8.8. setMinor 4142 public void setMinor(int minorCode, String message) 4144 Used internally by the GSS-API implementation and the underlying 4145 mechanisms to set the minor code and its textual representation. 4147 Parameters: 4149 minorCode The mechanism-specific error code. 4151 message A textual explanation of the mechanism error 4152 code. 4154 6.8.9. toString 4156 public String toString() 4158 Returns a textual representation of both the major and minor status 4159 codes. 4161 6.8.10. getMessage 4163 public String getMessage() 4165 Returns a detailed message of this exception. Overrides 4166 Throwable.getMessage. It is customary in Java to use this method to 4167 obtain exception information. 4169 7. Sample Applications 4171 7.1. Simple GSS Context Initiator 4173 4174 import org.ietf.jgss.*; 4176 /** 4177 * This is a partial sketch for a simple client program that acts 4178 * as a GSS context initiator. It illustrates how to use the Java 4179 * bindings for the GSS-API specified in 4180 * Generic Security Service API Version 2 : Java bindings 4181 * 4182 * 4183 * This code sketch assumes the existence of a GSS-API 4184 * implementation that supports the mechanism that it will need 4185 * and is present as a library package (org.ietf.jgss) either as 4186 * part of the standard JRE or in the CLASSPATH the application 4187 * specifies. 4189 */ 4191 public class SimpleClient { 4193 private String serviceName; // name of peer (i.e., server) 4194 private GSSCredential clientCred = null; 4195 private GSSContext context = null; 4196 private Oid mech; // underlying mechanism to use 4198 private GSSManager mgr = GSSManager.getInstance(); 4200 ... 4201 ... 4203 private void clientActions() { 4204 initializeGSS(); 4205 establishContext(); 4206 doCommunication(); 4207 } 4209 /** 4210 * Acquire credentials for the client. 4211 */ 4212 private void initializeGSS() { 4214 try { 4216 clientCred = mgr.createCredential(null /*default princ*/, 4217 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 4218 mech /* mechanism to use */, 4219 GSSCredential.INITIATE_ONLY /* init context */); 4221 print("GSSCredential created for " + 4222 cred.getName().toString()); 4223 print("Credential lifetime (sec)=" + 4224 cred.getRemainingLifetime()); 4225 } catch (GSSException e) { 4226 print("GSS-API error in credential acquisition: " 4227 + e.getMessage()); 4228 ... 4229 ... 4230 } 4231 ... 4232 ... 4233 } 4235 /** 4236 * Does the security context establishment with the 4237 * server. 4238 */ 4239 private void establishContext() { 4241 byte[] inToken = new byte[0]; 4242 byte[] outToken = null; 4244 try { 4246 GSSName peer = mgr.createName(serviceName, 4247 GSSName.NT_HOSTBASED_SERVICE); 4248 context = mgr.createContext(peer, mech, gssCred, 4249 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 4251 // Will need to support confidentiality 4252 context.requestConf(true); 4254 while (!context.isEstablished()) { 4256 outToken = context.initSecContext(inToken, 0, 4257 inToken.length); 4259 if (outToken != null) 4260 writeGSSToken(outToken); 4262 if (!context.isEstablished()) 4263 inToken = readGSSToken(); 4264 } 4266 GSSName peer = context.getSrcName(); 4267 print("Security context established with " + peer + 4268 " using underlying mechanism " + mech.toString()); 4269 } catch (GSSException e) { 4270 print("GSS-API error during context establishment: " 4271 + e.getMessage()); 4273 // If the exception contains an output token, 4274 // it should be sent to the acceptor. 4275 byte[] outTok = e.getOutputToken(); 4276 if (outTok != null) { 4277 writeGSSToken(outTok); 4278 } 4279 ... 4280 ... 4281 } 4282 ... 4283 ... 4284 } 4285 /** 4286 * Sends some data to the server and reads back the 4287 * response. 4288 */ 4289 private void doCommunication() { 4290 byte[] inToken = null; 4291 byte[] outToken = null; 4292 byte[] buffer; 4294 // Container for multiple input-output arguments to and 4295 // from the per-message routines (e.g., wrap/unwrap). 4296 MessageProp messgInfo = new MessageProp(); 4298 try { 4300 /* 4301 * Now send some bytes to the server to be 4302 * processed. They will be integrity protected 4303 * but not encrypted for privacy. 4304 */ 4306 buffer = readFromFile(); 4308 // Set privacy to "false" and use the default QOP 4309 messgInfo.setPrivacy(false); 4311 outToken = context.wrap(buffer, 0, buffer.length, 4312 messgInfo); 4314 writeGSSToken(outToken); 4316 /* 4317 * Now read the response from the server. 4318 */ 4320 inToken = readGSSToken(); 4321 buffer = context.unwrap(inToken, 0, 4322 inToken.length, messgInfo); 4323 // All ok if no exception was thrown! 4325 GSSName peer = context.getSrcName(); 4327 print("Message from " + peer.toString() 4328 + " arrived."); 4329 print("Was it encrypted? " + 4330 messgInfo.getPrivacy()); 4331 print("Duplicate Token? " + 4332 messgInfo.isDuplicateToken()); 4334 print("Old Token? " + 4335 messgInfo.isOldToken()); 4336 print("Unsequenced Token? " + 4337 messgInfo.isUnseqToken()); 4338 print("Gap Token? " + 4339 messgInfo.isGapToken()); 4340 ... 4341 ... 4342 } catch (GSSException e) { 4343 print("GSS-API error in per-message calls: " 4344 + e.getMessage()); 4345 ... 4346 ... 4347 } 4348 ... 4349 ... 4350 } // end of doCommunication method 4352 ... 4353 ... 4355 } // end of class SimpleClient 4356 4358 7.2. Simple GSS Context Acceptor 4360 4361 import org.ietf.jgss.*; 4363 /** 4364 * This is a partial sketch for a simple server program that acts 4365 * as a GSS context acceptor. It illustrates how to use the Java 4366 * bindings for the GSS-API specified in 4367 * Generic Security Service API Version 2 : Java bindings. 4368 * 4369 * This code sketch assumes the existence of a GSS-API 4370 * implementation that supports the mechanisms that it will need 4371 * and is present as a library package (org.ietf.jgss) either as 4372 * part of the standard JRE or in the CLASSPATH the application 4373 * specifies. 4374 */ 4376 import org.ietf.jgss.*; 4378 public class SimpleServer { 4380 private String serviceName; 4381 private GSSName name; 4382 private GSSCredential cred; 4384 private GSSManager mgr; 4386 ... 4387 ... 4389 /** 4390 * Wait for client connections, establish security contexts 4391 * and provide service. 4392 */ 4393 private void loop() { 4394 ... 4395 ... 4396 mgr = GSSManager.getInstance(); 4398 name = mgr.createName(serviceName, 4399 GSSName.NT_HOSTBASED_SERVICE); 4401 cred = mgr.createCredential(name, 4402 GSSCredential.INDEFINITE_LIFETIME, 4403 null, 4404 GSSCredential.ACCEPT_ONLY); 4406 // Loop infinitely 4407 while (true) { 4408 Socket s = serverSock.accept(); 4410 // Start a new thread to serve this connection 4411 Thread serverThread = new ServerThread(s); 4412 serverThread.start(); 4413 } 4414 } 4416 /** 4417 * Inner class ServerThread whose run() method provides the 4418 * secure service to a connection. 4419 */ 4421 private class ServerThread extends Thread { 4423 ... 4424 ... 4426 /** 4427 * Deals with the connection from one client. It also 4428 * handles all GSSException's thrown while talking to 4429 * this client. 4431 */ 4432 public void run() { 4434 byte[] inToken = null; 4435 byte[] outToken = null; 4436 byte[] buffer; 4438 GSSName peer; 4440 // Container for multiple input-output arguments to 4441 // and from the per-message routines 4442 // (i.e., wrap/unwrap). 4443 MessageProp supplInfo = new MessageProp(); 4444 GSSContext secContext = null; 4446 try { 4447 // Now do the context establishment loop 4448 GSSContext context = mgr.createContext(cred); 4450 while (!context.isEstablished()) { 4452 inToken = readGSSToken(); 4453 outToken = context.acceptSecContext(inToken, 4454 0, inToken.length); 4455 if (outToken != null) 4456 writeGSSToken(outToken); 4457 } 4459 // SimpleServer wants confidentiality to be 4460 // available. Check for it. 4461 if (!context.getConfState()){ 4462 ... 4463 ... 4464 } 4466 GSSName peer = context.getSrcName(); 4467 Oid mech = context.getMech(); 4468 print("Security context established with " + 4469 peer.toString() + 4470 " using underlying mechanism " + 4471 mech.toString() + 4472 " from Provider " + 4473 context.getProvider().getName()); 4475 // Now read the bytes sent by the client to be 4476 // processed. 4477 inToken = readGSSToken(); 4478 // Unwrap the message 4479 buffer = context.unwrap(inToken, 0, 4480 inToken.length, supplInfo); 4481 // All ok if no exception was thrown! 4483 // Print other supplementary per-message status 4484 // information. 4486 print("Message from " + 4487 peer.toString() + " arrived."); 4488 print("Was it encrypted? " + 4489 supplInfo.getPrivacy()); 4490 print("Duplicate Token? " + 4491 supplInfo.isDuplicateToken()); 4492 print("Old Token? " + supplInfo.isOldToken()); 4493 print("Unsequenced Token? " + 4494 supplInfo.isUnseqToken()); 4495 print("Gap Token? " + supplInfo.isGapToken()); 4497 /* 4498 * Now process the bytes and send back an 4499 * encrypted response. 4500 */ 4502 buffer = serverProcess(buffer); 4504 // Encipher it and send it across 4506 supplInfo.setPrivacy(true); // privacy requested 4507 supplInfo.setQOP(0); // default QOP 4508 outToken = context.wrap(buffer, 0, buffer.length, 4509 supplInfo); 4510 writeGSSToken(outToken); 4512 } catch (GSSException e) { 4513 print("GSS-API Error: " + e.getMessage()); 4514 // Alternatively, could call e.getMajorMessage() 4515 // and e.getMinorMessage() 4517 // If the exception contains an output token, 4518 // it should be sent to the initiator. 4519 byte[] outTok = e.getOutputToken(); 4520 if (outTok != null) { 4521 writeGSSToken(outTok); 4522 } 4523 print("Abandoning security context."); 4524 ... 4525 ... 4527 } 4528 ... 4529 ... 4530 } // end of run method in ServerThread 4532 } // end of inner class ServerThread 4534 ... 4535 ... 4537 } // end of class SimpleServer 4538 4540 8. Security Considerations 4542 The Java language security model allows platform providers to have 4543 policy-based fine-grained access control over any resource that an 4544 application wants. When using a Java security manager (such as, but 4545 not limited to, the case of applets running in browsers) the 4546 application code is in a sandbox by default. 4548 Administrators of the platform JRE determine what permissions, if 4549 any, are to be given to source from different codebases. Thus, the 4550 administrator has to be aware of any special requirements that the 4551 GSS provider might have for system resources. For instance, a 4552 Kerberos provider might wish to make a network connection to the Key 4553 Distribution Center (KDC) to obtain initial credentials. This would 4554 not be allowed under the sandbox unless the administrator had granted 4555 permissions for this. Also, note that this granting and checking of 4556 permissions happens transparently to the application and is outside 4557 the scope of this document. 4559 The Java language allows administrators to pre-configure a list of 4560 security service providers in the /lib/security/java.security 4561 file. At runtime, the system approaches these providers in order of 4562 preference when looking for security related services. Applications 4563 have a means to modify this list through methods in the "Security" 4564 class in the "java.security" package. However, since these 4565 modifications would be visible in the entire Java Virtual Machine 4566 (JVM) and thus affect all code executing in it, this operation is not 4567 available in the sandbox and requires special permissions to perform. 4568 Thus, when a GSS application has special needs that are met by a 4569 particular security provider, it has two choices: 4571 1) To install the provider on a JVM-wide basis using the 4572 java.security.Security class and then depend on the system to find 4573 the right provider automatically when the need arises. (This 4574 would require the application to be granted a "insertProvider 4575 SecurityPermission".) 4577 2) To pass an instance of the provider to the local instance of 4578 GSSManager so that only factory calls going through that 4579 GSSManager use the desired provider. (This would not require any 4580 permissions.) 4582 9. IANA Considerations 4584 This document has no actions for IANA. 4586 10. Acknowledgments 4588 This proposed API leverages earlier work performed by the IETF's CAT 4589 WG as outlined in both RFC 2743 [RFC2743] and RFC 2744 [RFC2744]. 4590 Many conceptual definitions, implementation directions, and 4591 explanations have been included from these documents. 4593 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4594 Saltz, and other members of Sun's development team for their helpful 4595 input, comments, and suggestions. 4597 We would also like to thank Joe Salowey, and Michael Smith for many 4598 insightful ideas and suggestions that have contributed to this 4599 document. 4601 11. Changes since RFC 5653 4603 There is a design flaw in the initSecContext and acceptSecContext 4604 methods of the GSSContext class defined in Generic Security Service 4605 API Version 2: Java Bindings Update [RFC5653]. 4607 The methods could either return a token (possibly null if no more 4608 tokens are needed) when the call succeeds or throw a GSSException if 4609 there is a failure, but NOT both. On the other hand, the C bindings 4610 of GSS-API [RFC2744] can return both, that is to say, a call to the 4611 GSS_Init_sec_context() function can return a major status code, and 4612 at the same time, fill in the output_token argument if there is one. 4614 Without the ability to emit an error token when there is a failure, a 4615 Java application has no mechanism to tell the other side what the 4616 error is. For example, a "reject" NegTokenResp token can never be 4617 transmitted for the SPNEGO mechanism [RFC4178]. 4619 While a Java method can never return a value and throw an exception 4620 at the same time, we can embed the error token inside the exception 4621 so that the caller has a chance to retrieve it. This update adds a 4622 new GSSException constructor to include this token inside a 4623 GSSException object, and a getOutputToken() method to retrieve the 4624 token. The specification for the initSecContext and acceptSecContext 4625 methods are updated to describe the new behavior. Various examples 4626 are also updated. 4628 This is a compatible change. New JGSS programs should make use of 4629 this new feature but it is not mandatory. 4631 12. Changes since RFC 2853 4633 This document has following changes: 4635 1) Major GSS Status Code Constant Values 4637 RFC 2853 listed all the GSS status code values in two different 4638 sections: section 4.12.1 defined numeric values for them, and 4639 section 6.8.1 defined them as static constants in the GSSException 4640 class without assigning any values. Due to an inconsistent 4641 ordering between these two sections, all of the GSS major status 4642 codes resulted in misalignment, and a subsequent disagreement 4643 between deployed implementations. 4645 This document defines the numeric values of the GSS status codes 4646 in both sections, while maintaining the original ordering from 4647 section 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status 4648 code values defined in section 4.12.1. The relevant sections in 4649 this document are sections 4.12.1 and 6.8.1. 4651 2) GSS Credential Usage Constant Values 4653 RFC 2853 section 6.3.2 defines static constants for the 4654 GSSCredential usage flags. However, the values of these constants 4655 were not defined anywhere in RFC 2853 [RFC2853]. 4657 This document defines the credential usage values in section 4658 6.3.2. The original ordering of these values from section 6.3.2 4659 of RFC 2853 [RFC2853] is maintained. 4661 3) GSS Host-Based Service Name 4663 RFC 2853 [RFC2853], section 6.2.2, defines the static constant for 4664 the GSS host-based service OID NT_HOSTBASED_SERVICE, using a 4665 deprecated OID value. 4667 This document updates the NT_HOSTBASED_SERVICE OID value in 4668 section 6.2.2 to be consistent with the C-bindings in RFC 2744 4669 [RFC2744]. 4671 13. References 4673 13.1. Normative References 4675 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism 4676 (SPKM)", RFC 2025, October 1996. 4678 [RFC2743] Linn, J., "Generic Security Service Application Program 4679 Interface Version 2, Update 1", RFC 2743, January 2000. 4681 [RFC2744] Wray, J., "Generic Security Service API Version 2 : 4682 C-bindings", RFC 2744, January 2000. 4684 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service API 4685 Version 2 : Java Bindings", RFC 2853, June 2000. 4687 [RFC4121] Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos 4688 Version 5 Generic Security Service Application Program 4689 Interface (GSS-API) Mechanism: Version 2", RFC 4121, July 4690 2005. 4692 [RFC4178] Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The 4693 Simple and Protected Generic Security Service Application 4694 Program Interface (GSS-API) Negotiation Mechanism", RFC 4695 4178, October 2005. 4697 [RFC5653] Upadhyay, M. and S. Malkani, "Generic Security Service API 4698 Version 2: Java Bindings Update", RFC 5653, August 2009. 4700 13.2. Informative References 4702 [JLS] Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java 4703 Language Specification", Third Edition, 2005, 4704 . 4706 Authors' Addresses 4708 Mayank D. Upadhyay 4709 Google Inc. 4710 1600 Amphitheatre Parkway 4711 Mountain View, CA 94043 4712 USA 4714 Email: m.d.upadhyay+ietf@gmail.com 4715 Seema Malkani 4716 ActivIdentity Corp. 4717 6623 Dumbarton Circle 4718 Fremont, California 94555 4719 USA 4721 Email: Seema.Malkani@gmail.com 4723 Wang Weijun 4724 Oracle 4725 Building No. 24, Zhongguancun Software Park 4726 Beijing 100193 4727 China 4729 Email: weijun.wang@oracle.com