idnits 2.17.1 draft-ietf-kitten-rfc2853bis-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 4477. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4454. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4461. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4467. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard 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. -- The abstract seems to indicate that this document obsoletes RFC2853, but the header doesn't have an 'Obsoletes:' line to match this. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (August 16, 2006) is 6464 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 4038 == Unused Reference: 'RFC4121' is defined on line 4417, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2853 (Obsoleted by RFC 5653) Summary: 4 errors (**), 0 flaws (~~), 5 warnings (==), 10 comments (--). 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 Expires: February 17, 2007 S. Malkani 5 Sun Microsystems 6 August 16, 2006 8 Generic Security Service API Version 2 : Java Bindings Update 9 draft-ietf-kitten-rfc2853bis-02.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on February 17, 2007. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 The Generic Security Services Application Program Interface (GSS-API) 43 offers application programmers uniform access to security services 44 atop a variety of underlying cryptographic mechanisms. This document 45 updates the Java bindings for the GSS-API that are specified in 46 "Generic Security Service API version 2 : Java Bindings" (RFC2853). 47 This document obsoletes RFC2853 by making specific and incremental 48 clarifications and corrections to it in response to identification of 49 transcription errors and implementation experience. The note-worthy 50 changes are in sections 4.12.1, 6.2.2, 6.3.2, and 6.8.1 of RFC2853, 51 which are replaced by the sections 5.12.1, 7.2.2, 7.3.2, and 7.8.1 of 52 this document, where numerical constants were either added or 53 modified. 55 The GSS-API is described at a language independent conceptual level 56 in "Generic Security Service Application Program Interface Version 2, 57 Update 1" (RFC2743). The GSS-API allows a caller application to 58 authenticate a principal identity, to delegate rights to a peer, and 59 to apply security services such as confidentiality and integrity on a 60 per-message basis. Examples of security mechanisms defined for GSS- 61 API are "The Simple Public-Key GSS-API Mechanism" (RFC2025) and "The 62 Kerberos Version 5 GSS-API Mechanism (RFC4121). 64 Table of Contents 66 1. Conventions Used in This Document . . . . . . . . . . . . . 7 67 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 8 68 3. GSS-API Operational Paradigm . . . . . . . . . . . . . . . . 9 69 4. Additional Controls . . . . . . . . . . . . . . . . . . . . 11 70 4.1 Delegation . . . . . . . . . . . . . . . . . . . . . . . . 12 71 4.2 Mutual Authentication . . . . . . . . . . . . . . . . . . 13 72 4.3 Replay and Out-of-Sequence Detection . . . . . . . . . . . 13 73 4.4 Anonymous Authentication . . . . . . . . . . . . . . . . . 14 74 4.5 Confidentiality . . . . . . . . . . . . . . . . . . . . . 15 75 4.6 Inter-process Context Transfer . . . . . . . . . . . . . . 15 76 4.7 The Use of Incomplete Contexts . . . . . . . . . . . . . . 16 77 5. Calling Conventions . . . . . . . . . . . . . . . . . . . . 17 78 5.1 Package Name . . . . . . . . . . . . . . . . . . . . . . . 17 79 5.2 Provider Framework . . . . . . . . . . . . . . . . . . . . 17 80 5.3 Integer Types . . . . . . . . . . . . . . . . . . . . . . 18 81 5.4 Opaque Data Types . . . . . . . . . . . . . . . . . . . . 18 82 5.5 Strings . . . . . . . . . . . . . . . . . . . . . . . . . 18 83 5.6 Object Identifiers . . . . . . . . . . . . . . . . . . . . 18 84 5.7 Object Identifier Sets . . . . . . . . . . . . . . . . . . 19 85 5.8 Credentials . . . . . . . . . . . . . . . . . . . . . . . 19 86 5.9 Contexts . . . . . . . . . . . . . . . . . . . . . . . . . 21 87 5.10 Authentication Tokens . . . . . . . . . . . . . . . . . 21 88 5.11 Interprocess Tokens . . . . . . . . . . . . . . . . . . 22 89 5.12 Error Reporting . . . . . . . . . . . . . . . . . . . . 22 90 5.12.1 GSS Status Codes . . . . . . . . . . . . . . . . . . 22 91 5.12.2 Mechanism-Specific Status Codes . . . . . . . . . . 25 92 5.12.3 Supplementary Status Codes . . . . . . . . . . . . . 25 93 5.13 Names . . . . . . . . . . . . . . . . . . . . . . . . . 26 94 5.14 Channel Bindings . . . . . . . . . . . . . . . . . . . . 28 95 5.15 Stream Objects . . . . . . . . . . . . . . . . . . . . . 29 96 5.16 Optional Parameters . . . . . . . . . . . . . . . . . . 29 98 6. Introduction to GSS-API Classes and Interfaces . . . . . . . 31 99 6.1 GSSManager class . . . . . . . . . . . . . . . . . . . . . 31 100 6.2 GSSName interface . . . . . . . . . . . . . . . . . . . . 32 101 6.3 GSSCredential interface . . . . . . . . . . . . . . . . . 32 102 6.4 GSSContext interface . . . . . . . . . . . . . . . . . . . 33 103 6.5 MessageProp class . . . . . . . . . . . . . . . . . . . . 35 104 6.6 GSSException class . . . . . . . . . . . . . . . . . . . . 35 105 6.7 Oid class . . . . . . . . . . . . . . . . . . . . . . . . 35 106 6.8 ChannelBinding class . . . . . . . . . . . . . . . . . . . 36 107 7. Detailed GSS-API Class Description . . . . . . . . . . . . . 37 108 7.1 public abstract class GSSManager . . . . . . . . . . . . . 37 109 7.1.1 Example Code . . . . . . . . . . . . . . . . . . . . . 38 110 7.1.2 getInstance . . . . . . . . . . . . . . . . . . . . . 38 111 7.1.3 getMechs . . . . . . . . . . . . . . . . . . . . . . . 38 112 7.1.4 getNamesForMech . . . . . . . . . . . . . . . . . . . 39 113 7.1.5 getMechsForName . . . . . . . . . . . . . . . . . . . 39 114 7.1.6 createName . . . . . . . . . . . . . . . . . . . . . . 39 115 7.1.7 createName . . . . . . . . . . . . . . . . . . . . . . 40 116 7.1.8 createName . . . . . . . . . . . . . . . . . . . . . . 40 117 7.1.9 createName . . . . . . . . . . . . . . . . . . . . . . 41 118 7.1.10 createCredential . . . . . . . . . . . . . . . . . . 41 119 7.1.11 createCredential . . . . . . . . . . . . . . . . . . 42 120 7.1.12 createCredential . . . . . . . . . . . . . . . . . . 42 121 7.1.13 createContext . . . . . . . . . . . . . . . . . . . 43 122 7.1.14 createContext . . . . . . . . . . . . . . . . . . . 43 123 7.1.15 createContext . . . . . . . . . . . . . . . . . . . 44 124 7.1.16 addProviderAtFront . . . . . . . . . . . . . . . . . 44 125 7.1.17 Example Code . . . . . . . . . . . . . . . . . . . . 45 126 7.1.18 addProviderAtEnd . . . . . . . . . . . . . . . . . . 46 127 7.1.19 Example Code . . . . . . . . . . . . . . . . . . . . 46 128 7.2 public interface GSSName . . . . . . . . . . . . . . . . . 47 129 7.2.1 Example Code . . . . . . . . . . . . . . . . . . . . . 47 130 7.2.2 Static Constants . . . . . . . . . . . . . . . . . . . 48 131 7.2.3 equals . . . . . . . . . . . . . . . . . . . . . . . . 49 132 7.2.4 equals . . . . . . . . . . . . . . . . . . . . . . . . 49 133 7.2.5 canonicalize . . . . . . . . . . . . . . . . . . . . . 50 134 7.2.6 export . . . . . . . . . . . . . . . . . . . . . . . . 50 135 7.2.7 toString . . . . . . . . . . . . . . . . . . . . . . . 50 136 7.2.8 getStringNameType . . . . . . . . . . . . . . . . . . 51 137 7.2.9 isAnonymous . . . . . . . . . . . . . . . . . . . . . 51 138 7.2.10 isMN . . . . . . . . . . . . . . . . . . . . . . . . 51 139 7.3 public interface GSSCredential implements Cloneable . . . 51 140 7.3.1 Example Code . . . . . . . . . . . . . . . . . . . . . 52 141 7.3.2 Static Constants . . . . . . . . . . . . . . . . . . . 53 142 7.3.3 dispose . . . . . . . . . . . . . . . . . . . . . . . 53 143 7.3.4 getName . . . . . . . . . . . . . . . . . . . . . . . 53 144 7.3.5 getName . . . . . . . . . . . . . . . . . . . . . . . 53 145 7.3.6 getRemainingLifetime . . . . . . . . . . . . . . . . . 54 146 7.3.7 getRemainingInitLifetime . . . . . . . . . . . . . . . 54 147 7.3.8 getRemainingAcceptLifetime . . . . . . . . . . . . . . 54 148 7.3.9 getUsage . . . . . . . . . . . . . . . . . . . . . . . 55 149 7.3.10 getUsage . . . . . . . . . . . . . . . . . . . . . . 55 150 7.3.11 getMechs . . . . . . . . . . . . . . . . . . . . . . 55 151 7.3.12 add . . . . . . . . . . . . . . . . . . . . . . . . 55 152 7.3.13 equals . . . . . . . . . . . . . . . . . . . . . . . 56 153 7.4 public interface GSSContext . . . . . . . . . . . . . . . 56 154 7.4.1 Example Code . . . . . . . . . . . . . . . . . . . . . 57 155 7.4.2 Static Constants . . . . . . . . . . . . . . . . . . . 59 156 7.4.3 initSecContext . . . . . . . . . . . . . . . . . . . . 59 157 7.4.4 Example Code . . . . . . . . . . . . . . . . . . . . . 61 158 7.4.5 initSecContext . . . . . . . . . . . . . . . . . . . . 61 159 7.4.6 Example Code . . . . . . . . . . . . . . . . . . . . . 62 160 7.4.7 acceptSecContext . . . . . . . . . . . . . . . . . . . 63 161 7.4.8 Example Code . . . . . . . . . . . . . . . . . . . . . 64 162 7.4.9 acceptSecContext . . . . . . . . . . . . . . . . . . . 65 163 7.4.10 Example Code . . . . . . . . . . . . . . . . . . . . 65 164 7.4.11 isEstablished . . . . . . . . . . . . . . . . . . . 66 165 7.4.12 dispose . . . . . . . . . . . . . . . . . . . . . . 66 166 7.4.13 getWrapSizeLimit . . . . . . . . . . . . . . . . . . 67 167 7.4.14 wrap . . . . . . . . . . . . . . . . . . . . . . . . 67 168 7.4.15 wrap . . . . . . . . . . . . . . . . . . . . . . . . 68 169 7.4.16 unwrap . . . . . . . . . . . . . . . . . . . . . . . 69 170 7.4.17 unwrap . . . . . . . . . . . . . . . . . . . . . . . 70 171 7.4.18 getMIC . . . . . . . . . . . . . . . . . . . . . . . 71 172 7.4.19 getMIC . . . . . . . . . . . . . . . . . . . . . . . 71 173 7.4.20 verifyMIC . . . . . . . . . . . . . . . . . . . . . 72 174 7.4.21 verifyMIC . . . . . . . . . . . . . . . . . . . . . 73 175 7.4.22 export . . . . . . . . . . . . . . . . . . . . . . . 73 176 7.4.23 requestMutualAuth . . . . . . . . . . . . . . . . . 74 177 7.4.24 requestReplayDet . . . . . . . . . . . . . . . . . . 74 178 7.4.25 requestSequenceDet . . . . . . . . . . . . . . . . . 75 179 7.4.26 requestCredDeleg . . . . . . . . . . . . . . . . . . 75 180 7.4.27 requestAnonymity . . . . . . . . . . . . . . . . . . 75 181 7.4.28 requestConf . . . . . . . . . . . . . . . . . . . . 76 182 7.4.29 requestInteg . . . . . . . . . . . . . . . . . . . . 76 183 7.4.30 requestLifetime . . . . . . . . . . . . . . . . . . 76 184 7.4.31 setChannelBinding . . . . . . . . . . . . . . . . . 76 185 7.4.32 getCredDelegState . . . . . . . . . . . . . . . . . 77 186 7.4.33 getMutualAuthState . . . . . . . . . . . . . . . . . 77 187 7.4.34 getReplayDetState . . . . . . . . . . . . . . . . . 77 188 7.4.35 getSequenceDetState . . . . . . . . . . . . . . . . 77 189 7.4.36 getAnonymityState . . . . . . . . . . . . . . . . . 78 190 7.4.37 isTransferable . . . . . . . . . . . . . . . . . . . 78 191 7.4.38 isProtReady . . . . . . . . . . . . . . . . . . . . 78 192 7.4.39 getConfState . . . . . . . . . . . . . . . . . . . . 78 193 7.4.40 getIntegState . . . . . . . . . . . . . . . . . . . 78 194 7.4.41 getLifetime . . . . . . . . . . . . . . . . . . . . 78 195 7.4.42 getSrcName . . . . . . . . . . . . . . . . . . . . . 79 196 7.4.43 getTargName . . . . . . . . . . . . . . . . . . . . 79 197 7.4.44 getMech . . . . . . . . . . . . . . . . . . . . . . 79 198 7.4.45 getDelegCred . . . . . . . . . . . . . . . . . . . . 79 199 7.4.46 isInitiator . . . . . . . . . . . . . . . . . . . . 79 200 7.5 public class MessageProp . . . . . . . . . . . . . . . . . 79 201 7.5.1 Constructors . . . . . . . . . . . . . . . . . . . . . 80 202 7.5.2 getQOP . . . . . . . . . . . . . . . . . . . . . . . . 80 203 7.5.3 getPrivacy . . . . . . . . . . . . . . . . . . . . . . 81 204 7.5.4 getMinorStatus . . . . . . . . . . . . . . . . . . . . 81 205 7.5.5 getMinorString . . . . . . . . . . . . . . . . . . . . 81 206 7.5.6 setQOP . . . . . . . . . . . . . . . . . . . . . . . . 81 207 7.5.7 setPrivacy . . . . . . . . . . . . . . . . . . . . . . 81 208 7.5.8 isDuplicateToken . . . . . . . . . . . . . . . . . . . 81 209 7.5.9 isOldToken . . . . . . . . . . . . . . . . . . . . . . 82 210 7.5.10 isUnseqToken . . . . . . . . . . . . . . . . . . . . 82 211 7.5.11 isGapToken . . . . . . . . . . . . . . . . . . . . . 82 212 7.5.12 setSupplementaryStates . . . . . . . . . . . . . . . 82 213 7.6 public class ChannelBinding . . . . . . . . . . . . . . . 83 214 7.6.1 Constructors . . . . . . . . . . . . . . . . . . . . . 83 215 7.6.2 getInitiatorAddress . . . . . . . . . . . . . . . . . 84 216 7.6.3 getAcceptorAddress . . . . . . . . . . . . . . . . . . 84 217 7.6.4 getApplicationData . . . . . . . . . . . . . . . . . . 84 218 7.6.5 equals . . . . . . . . . . . . . . . . . . . . . . . . 84 219 7.7 public class Oid . . . . . . . . . . . . . . . . . . . . . 84 220 7.7.1 Constructors . . . . . . . . . . . . . . . . . . . . . 85 221 7.7.2 toString . . . . . . . . . . . . . . . . . . . . . . . 85 222 7.7.3 equals . . . . . . . . . . . . . . . . . . . . . . . . 86 223 7.7.4 getDER . . . . . . . . . . . . . . . . . . . . . . . . 86 224 7.7.5 containedIn . . . . . . . . . . . . . . . . . . . . . 86 225 7.8 public class GSSException extends Exception . . . . . . . 86 226 7.8.1 Static Constants . . . . . . . . . . . . . . . . . . . 87 227 7.8.2 Constructors . . . . . . . . . . . . . . . . . . . . . 89 228 7.8.3 getMajor . . . . . . . . . . . . . . . . . . . . . . . 90 229 7.8.4 getMinor . . . . . . . . . . . . . . . . . . . . . . . 90 230 7.8.5 getMajorString . . . . . . . . . . . . . . . . . . . . 90 231 7.8.6 getMinorString . . . . . . . . . . . . . . . . . . . . 90 232 7.8.7 setMinor . . . . . . . . . . . . . . . . . . . . . . . 90 233 7.8.8 toString . . . . . . . . . . . . . . . . . . . . . . . 90 234 7.8.9 getMessage . . . . . . . . . . . . . . . . . . . . . . 91 235 8. Sample Applications . . . . . . . . . . . . . . . . . . . . 92 236 8.1 Simple GSS Context Initiator . . . . . . . . . . . . . . . 92 237 8.2 Simple GSS Context Acceptor . . . . . . . . . . . . . . . 95 238 9. Security Considerations . . . . . . . . . . . . . . . . . . 100 239 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 101 240 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 102 241 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 103 242 12.1 Normative References . . . . . . . . . . . . . . . . . . 103 243 12.2 Informative References . . . . . . . . . . . . . . . . . 103 244 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 103 245 Intellectual Property and Copyright Statements . . . . . . . 105 247 1. Conventions Used in This Document 249 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 250 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 251 document are to be interpreted as described in [RFC2119]. 253 2. Introduction 255 This document specifies Java language bindings for the Generic 256 Security Services Application Programming Interface Version 2 (GSS- 257 API). GSS-API Version 2 is described in a language independent 258 format in RFC 2743 [GSSAPIv2-UPDATE]. The GSS-API allows a caller 259 application to authenticate a principal identity, to delegate rights 260 to a peer, and to apply security services such as confidentiality and 261 integrity on a per-message basis. 263 This document and its predecessor RFC 2853 [RFC2853] leverage the 264 work done by the WG in the area of RFC 2743 [GSSAPIv2-UPDATE] and the 265 C-bindings RFC 2744 [GSSAPI-Cbind]. Whenever appropriate, text has 266 been used from the C-bindings RFC 2744 to explain generic concepts 267 and provide direction to the implementors. 269 The design goals of this API have been to satisfy all the 270 functionality defined in RFC 2743 and to provide these services in an 271 object oriented method. The specification also aims to satisfy the 272 needs of both types of Java application developers, those who would 273 like access to a "system-wide" GSS-API implementation, as well as 274 those who would want to provide their own "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- 292 wide" basis, where all users of the framework will have them 293 available. The specification also allows for the addition of 294 mechanisms per-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 3. GSS-API Operational Paradigm 302 The Generic Security Service Application Programming Interface 303 Version 2 [GSSAPIv2-UPDATE] defines a generic security API to calling 304 applications. It allows a communicating application to authenticate 305 the user associated with another application, to delegate rights to 306 another application, and to apply security services such as 307 confidentiality 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 credentials 313 vouch for its global identity, which may or may not be related to any 314 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 encapsulates 318 shared state information, which is required in order that per-message 319 security services may be provided. Examples of state information 320 that might be shared between applications as part of a security 321 context are cryptographic keys, and message sequence numbers. As 322 part of the establishment of a security context, the context 323 initiator is authenticated to the responder, and may require that the 324 responder is authenticated back to the initiator. The initiator may 325 optionally give the responder the right to initiate further security 326 contexts, acting as an agent or delegate of the initiator. This 327 transfer of rights is termed "delegation", and is achieved by 328 creating a set of credentials, similar to those used by the 329 initiating application, but which may be used by the responder. 331 A GSSContext object is used to establish and maintain the shared 332 information that makes up the security context. Certain GSSContext 333 methods will generate a token, which applications treat as 334 cryptographically protected, opaque data. The caller of such 335 GSSContext method is responsible for transferring the token to the 336 peer application, encapsulated if necessary in an application-to- 337 application protocol. On receipt of such a token, the peer 338 application should pass it to a corresponding GSSContext method which 339 will decode the token and extract the information, updating the 340 security context state information accordingly. 342 3) Per-message services are invoked on a GSSContext object to apply 343 either: 345 integrity and data origin authentication, or 347 confidentiality, integrity and data origin authentication 348 to application data, which are treated by GSS-API as arbitrary octet- 349 strings. An application transmitting a message that it wishes to 350 protect will call the appropriate GSSContext method (getMIC or wrap) 351 to apply protection, and send the resulting token to the receiving 352 application. The receiver will pass the received token (and, in the 353 case of data protected by getMIC, the accompanying message-data) to 354 the corresponding decoding method of the GSSContext interface 355 (verifyMIC or unwrap) to remove the protection and validate the data. 357 4) At the completion of a communications session (which may extend 358 across several transport connections), each application uses a 359 GSSContext method to invalidate the security context and release any 360 system or cryptographic resources held. Multiple contexts may also 361 be used (either successively or simultaneously) within a single 362 communications association, at the discretion of the applications. 364 4. Additional Controls 366 This section discusses the optional services that a context initiator 367 may request of the GSS-API before the context establishment. Each of 368 these services is requested by calling the appropriate mutator method 369 in the GSSContext object before the first call to init is performed. 370 Only the context initiator can request context flags. 372 The optional services defined are: 374 Delegation The (usually temporary) transfer of rights from 375 initiator to acceptor, enabling the acceptor to authenticate 376 itself as an agent of the initiator. 378 Mutual Authentication In addition to the initiator authenticating 379 its identity to the context acceptor, the context acceptor should 380 also authenticate itself to the initiator. 382 Replay Detection In addition to providing message integrity 383 services, GSSContext per-message operations of getMIC and wrap 384 should include message numbering information to enable verifyMIC 385 and unwrap to detect if a message has been duplicated. 387 Out-of-Sequence Detection In addition to providing message 388 integrity services, GSSContext per-message operations (getMIC and 389 wrap) should include message sequencing information to enable 390 verifyMIC and unwrap to detect if a message has been received out 391 of sequence. 393 Anonymous Authentication The establishment of the security context 394 should not reveal the initiator's identity to the context 395 acceptor. 397 Some mechanisms may not support all optional services, and some 398 mechanisms may only support some services in conjunction with others. 399 The GSSContext interface offers query methods to allow the 400 verification by the calling application of which services will be 401 available from the context when the establishment phase is complete. 402 In general, if the security mechanism is capable of providing a 403 requested service, it should do so even if additional services must 404 be enabled in order to provide the requested service. If the 405 mechanism is incapable of providing a requested service, it should 406 proceed without the service leaving the application to abort the 407 context establishment process if it considers the requested service 408 to be mandatory. 410 Some mechanisms may specify that support for some services is 411 optional, and that implementors of the mechanism need not provide it. 413 This is most commonly true of the confidentiality service, often 414 because of legal restrictions on the use of data-encryption, but may 415 apply to any of the services. Such mechanisms are required to send 416 at least one token from acceptor to initiator during context 417 establishment when the initiator indicates a desire to use such a 418 service, so that the initiating GSS-API can correctly indicate 419 whether the service is supported by the acceptor's GSS-API. 421 4.1 Delegation 423 The GSS-API allows delegation to be controlled by the initiating 424 application via the requestCredDeleg method before the first call to 425 init has been issued. Some mechanisms do not support delegation, and 426 for such mechanisms attempts by an application to enable delegation 427 are ignored. 429 The acceptor of a security context, for which the initiator enabled 430 delegation, can check if delegation was enabled by using the 431 getCredDelegState method of the GSSContext interface. In cases when 432 it is, the delegated credential object can be obtained by calling the 433 getDelegCred method. The obtained GSSCredential object may then be 434 used to initiate subsequent GSS-API security contexts as an agent or 435 delegate of the initiator. If the original initiator's identity is 436 "A" and the delegate's identity is "B", then, depending on the 437 underlying mechanism, the identity embodied by the delegated 438 credential may be either "A" or "B acting for A". 440 For many mechanisms that support delegation, a simple boolean does 441 not provide enough control. Examples of additional aspects of 442 delegation control that a mechanism might provide to an application 443 are duration of delegation, network addresses from which delegation 444 is valid, and constraints on the tasks that may be performed by a 445 delegate. Such controls are presently outside the scope of the GSS- 446 API. GSS-API implementations supporting mechanisms offering 447 additional controls should provide extension routines that allow 448 these controls to be exercised (perhaps by modifying the initiator's 449 GSS-API credential object prior to its use in establishing a 450 context). However, the simple delegation control provided by GSS-API 451 should always be able to over-ride other mechanism-specific 452 delegation controls. If the application instructs the GSSContext 453 object that delegation is not desired, then the implementation must 454 not permit delegation to occur. This is an exception to the general 455 rule that a mechanism may enable services even if they are not 456 requested - delegation may only be provided at the explicit request 457 of the application. 459 4.2 Mutual Authentication 461 Usually, a context acceptor will require that a context initiator 462 authenticate itself so that the acceptor may make an access-control 463 decision prior to performing a service for the initiator. In some 464 cases, the initiator may also request that the acceptor authenticate 465 itself. GSS-API allows the initiating application to request this 466 mutual authentication service by calling the requestMutualAuth method 467 of the GSSContext interface with a "true" parameter before making the 468 first call to init. The initiating application is informed as to 469 whether or not the context acceptor has authenticated itself. Note 470 that some mechanisms may not support mutual authentication, and other 471 mechanisms may always perform mutual authentication, whether or not 472 the initiating application requests it. In particular, mutual 473 authentication may be required by some mechanisms in order to support 474 replay or out-of-sequence message detection, and for such mechanisms 475 a request for either of these services will automatically enable 476 mutual authentication. 478 4.3 Replay and Out-of-Sequence Detection 480 The GSS-API may provide detection of mis-ordered messages once a 481 security context has been established. Protection may be applied to 482 messages by either application, by calling either getMIC or wrap 483 methods of the GSSContext interface, and verified by the peer 484 application by calling verifyMIC or unwrap for the peer's GSSContext 485 object. 487 The getMIC method calculates a cryptographic checksum of an 488 application message, and returns that checksum in a token. The 489 application should pass both the token and the message to the peer 490 application, which presents them to the verifyMIC method of the 491 peer's GSSContext object. 493 The wrap method calculates a cryptographic checksum of an application 494 message, and places both the checksum and the message inside a single 495 token. The application should pass the token to the peer 496 application, which presents it to the unwrap method of the peer's 497 GSSContext object to extract the message and verify the checksum. 499 Either pair of routines may be capable of detecting out-of-sequence 500 message delivery, or duplication of messages. Details of such mis- 501 ordered messages are indicated through supplementary query methods of 502 the MessageProp object that is filled in by each of these routines. 504 A mechanism need not maintain a list of all tokens that have been 505 processed in order to support these status codes. A typical 506 mechanism might retain information about only the most recent "N" 507 tokens processed, allowing it to distinguish duplicates and missing 508 tokens within the most recent "N" messages; the receipt of a token 509 older than the most recent "N" would result in the isOldToken method 510 of the instance of MessageProp to return "true". 512 4.4 Anonymous Authentication 514 In certain situations, an application may wish to initiate the 515 authentication process to authenticate a peer, without revealing its 516 own identity. As an example, consider an application providing 517 access to a database containing medical information, and offering 518 unrestricted access to the service. A client of such a service might 519 wish to authenticate the service (in order to establish trust in any 520 information retrieved from it), but might not wish the service to be 521 able to obtain the client's identity (perhaps due to privacy concerns 522 about the specific inquiries, or perhaps simply to avoid being placed 523 on mailing-lists). 525 In normal use of the GSS-API, the initiator's identity is made 526 available to the acceptor as a result of the context establishment 527 process. However, context initiators may request that their identity 528 not be revealed to the context acceptor. Many mechanisms do not 529 support anonymous authentication, and for such mechanisms the request 530 will not be honored. An authentication token will still be 531 generated, but the application is always informed if a requested 532 service is unavailable, and has the option to abort context 533 establishment if anonymity is valued above the other security 534 services that would require a context to be established. 536 In addition to informing the application that a context is 537 established anonymously (via the isAnonymous method of the GSSContext 538 class), the getSrcName method of the acceptor's GSSContext object 539 will, for such contexts, return a reserved internal-form name, 540 defined by the implementation. 542 The toString method for a GSSName object representing an anonymous 543 entity will return a printable name. The returned value will be 544 syntactically distinguishable from any valid principal name supported 545 by the implementation. The associated name-type object identifier 546 will be an oid representing the value of NT_ANONYMOUS. This name- 547 type oid will be defined as a public, static Oid object of the 548 GSSName class. The printable form of an anonymous name should be 549 chosen such that it implies anonymity, since this name may appear in, 550 for example, audit logs. For example, the string "" might 551 be a good choice, if no valid printable names supported by the 552 implementation can begin with "<" and end with ">". 554 When using the equal method of the GSSName interface, and one of the 555 operands is a GSSName instance representing an anonymous entity, the 556 method must return "false". 558 4.5 Confidentiality 560 If a GSSContext supports the confidentiality service, wrap method may 561 be used to encrypt application messages. Messages are selectively 562 encrypted, under the control of the setPrivacy method of the 563 MessageProp object used in the wrap method. 565 4.6 Inter-process Context Transfer 567 GSS-API V2 provides functionality which allows a security context to 568 be transferred between processes on a single machine. These are 569 implemented using the export method of GSSContext and a byte array 570 constructor of the same class. The most common use for such a 571 feature is a client-server design where the server is implemented as 572 a single process that accepts incoming security contexts, which then 573 launches child processes to deal with the data on these contexts. In 574 such a design, the child processes must have access to the security 575 context object created within the parent so that they can use per- 576 message protection services and delete the security context when the 577 communication session ends. 579 Since the security context data structure is expected to contain 580 sequencing information, it is impractical in general to share a 581 context between processes. Thus GSSContext interface provides an 582 export method that the process, which currently owns the context, can 583 call to declare that it has no intention to use the context 584 subsequently, and to create an inter-process token containing 585 information needed by the adopting process to successfully re-create 586 the context. After successful completion of export, the original 587 security context is made inaccessible to the calling process by GSS- 588 API and any further usage of this object will result in failures. 589 The originating process transfers the inter-process token to the 590 adopting process, which creates a new GSSContext object using the 591 byte array constructor. The properties of the context are equivalent 592 to that of the original context. 594 The inter-process token may contain sensitive data from the original 595 security context (including cryptographic keys). Applications using 596 inter-process tokens to transfer security contexts must take 597 appropriate steps to protect these tokens in transit. 599 Implementations are not required to support the inter-process 600 transfer of security contexts. Calling the isTransferable method of 601 the GSSContext interface will indicate if the context object is 602 transferable. 604 4.7 The Use of Incomplete Contexts 606 Some mechanisms may allow the per-message services to be used before 607 the context establishment process is complete. For example, a 608 mechanism may include sufficient information in its initial context- 609 level tokens for the context acceptor to immediately decode messages 610 protected with wrap or getMIC. For such a mechanism, the initiating 611 application need not wait until subsequent context-level tokens have 612 been sent and received before invoking the per-message protection 613 services. 615 An application can invoke the isProtReady method of the GSSContext 616 class to determine if the per-message services are available in 617 advance of complete context establishment. Applications wishing to 618 use per-message protection services on partially-established contexts 619 should query this method before attempting to invoke wrap or getMIC. 621 5. Calling Conventions 623 Java provides the implementors with not just a syntax for the 624 language, but also an operational environment. For example, memory 625 is automatically managed and does not require application 626 intervention. These language features have allowed for a simpler API 627 and have led to the elimination of certain GSS-API functions. 629 Moreover, the JCA defines a provider model which allows for 630 implementation independent access to security services. Using this 631 model, applications can seamlessly switch between different 632 implementations and dynamically add new services. The GSS-API 633 specification leverages these concepts by the usage of providers for 634 the mechanism implementations. 636 5.1 Package Name 638 The classes and interfaces defined in this document reside in the 639 package called "org.ietf.jgss". Applications that wish to make use 640 of this API should import this package name as shown in section 8. 642 5.2 Provider Framework 644 The Java security API's use a provider architecture that allows 645 applications to be implementation independent and security API 646 implementations to be modular and extensible. The 647 java.security.Provider class is an abstract class that a vendor 648 extends. This class maps various properties that represent different 649 security services that are available to the names of the actual 650 vendor classes that implement those services. When requesting a 651 service, an application simply specifies the desired provider and the 652 API delegates the request to service classes available from that 653 provider. 655 Using the Java security provider model insulates applications from 656 implementation details of the services they wish to use. 657 Applications can switch between providers easily and new providers 658 can be added as needed, even at runtime. 660 The GSS-API may use providers to find components for specific 661 underlying security mechanisms. For instance, a particular provider 662 might contain components that will allow the GSS-API to support the 663 Kerberos v5 mechanism and another might contain components to support 664 the SPKM [RFC2025] mechanism. By delegating mechanism specific 665 functionality to the components obtained from providers the GSS-API 666 can be extended to support an arbitrary list of mechanism. 668 How the GSS-API locates and queries these providers is beyond the 669 scope of this document and is being deferred to a Service Provider 670 Interface (SPI) specification. The availability of such a SPI 671 specification is not mandatory for the adoption of this API 672 specification nor is it mandatory to use providers in the 673 implementation of a GSS-API framework. However, by using the 674 provider framework together with an SPI specification one can create 675 an extensible and implementation independent GSS-API framework. 677 5.3 Integer Types 679 All numeric values are declared as "int" primitive Java type. The 680 Java specification guarantees that this will be a 32 bit two's 681 complement signed number. 683 Throughout this API, the "boolean" primitive Java type is used 684 wherever a boolean value is required or returned. 686 5.4 Opaque Data Types 688 Java byte arrays are used to represent opaque data types which are 689 consumed and produced by the GSS-API in the forms of tokens. Java 690 arrays contain a length field which enables the users to easily 691 determine their size. The language has automatic garbage collection 692 which alleviates the need by developers to release memory and 693 simplifies buffer ownership issues. 695 5.5 Strings 697 The String object will be used to represent all textual data. The 698 Java String object, transparently treats all characters as two-byte 699 Unicode characters which allows support for many locals. All 700 routines returning or accepting textual data will use the String 701 object. 703 5.6 Object Identifiers 705 An Oid object will be used to represent Universal Object Identifiers 706 (Oids). Oids are ISO-defined, hierarchically globally-interpretable 707 identifiers used within the GSS-API framework to identify security 708 mechanisms and name formats. The Oid object can be created from a 709 string representation of its dot notation (e.g. "1.3.6.1.5.6.2") as 710 well as from its ASN.1 DER encoding. Methods are also provided to 711 test equality and provide the DER representation for the object. 713 An important feature of the Oid class is that its instances are 714 immutable - i.e. there are no methods defined that allow one to 715 change the contents of an Oid. This property allows one to treat 716 these objects as "statics" without the need to perform copies. 718 Certain routines allow the usage of a default oid. A "null" value 719 can be used in those cases. 721 5.7 Object Identifier Sets 723 The Java bindings represents object identifiers sets as arrays of Oid 724 objects. All Java arrays contain a length field which allows for 725 easy manipulation and reference. 727 In order to support the full functionality of RFC 2743, the Oid class 728 includes a method which checks for existence of an Oid object within 729 a specified array. This is equivalent in functionality to 730 gss_test_oid_set_member. The use of Java arrays and Java's automatic 731 garbage collection has eliminated the need for the following 732 routines: gss_create_empty_oid_set, gss_release_oid_set, and 733 gss_add_oid_set_member. Java GSS-API implementations will not 734 contain them. Java's automatic garbage collection and the immutable 735 property of the Oid object eliminates the complicated memory 736 management issues of the C counterpart. 738 When ever a default value for an Object Identifier Set is required, a 739 "null" value can be used. Please consult the detailed method 740 description for details. 742 5.8 Credentials 744 GSS-API credentials are represented by the GSSCredential interface. 745 The interface contains several constructs to allow for the creation 746 of most common credential objects for the initiator and the acceptor. 747 Comparisons are performed using the interface's "equals" method. The 748 following general description of GSS-API credentials is included from 749 the C-bindings specification: 751 GSS-API credentials can contain mechanism-specific principal 752 authentication data for multiple mechanisms. A GSS-API credential is 753 composed of a set of credential-elements, each of which is applicable 754 to a single mechanism. A credential may contain at most one 755 credential-element for each supported mechanism. A credential- 756 element identifies the data needed by a single mechanism to 757 authenticate a single principal, and conceptually contains two 758 credential-references that describe the actual mechanism-specific 759 authentication data, one to be used by GSS-API for initiating 760 contexts, and one to be used for accepting contexts. For mechanisms 761 that do not distinguish between acceptor and initiator credentials, 762 both references would point to the same underlying mechanism-specific 763 authentication data. 765 Credentials describe a set of mechanism-specific principals, and give 766 their holder the ability to act as any of those principals. All 767 principal identities asserted by a single GSS-API credential should 768 belong to the same entity, although enforcement of this property is 769 an implementation-specific matter. A single GSSCredential object 770 represents all the credential elements that have been acquired. 772 The creation's of an GSSContext object allows the value of "null" to 773 be specified as the GSSCredential input parameter. This will 774 indicate a desire by the application to act as a default principal. 775 While individual GSS-API implementations are free to determine such 776 default behavior as appropriate to the mechanism, the following 777 default behavior by these routines is recommended for portability: 779 For the initiator side of the context: 781 1) If there is only a single principal capable of initiating security 782 contexts for the chosen mechanism that the application is authorized 783 to act on behalf of, then that principal shall be used, otherwise 785 2) If the platform maintains a concept of a default network- identity 786 for the chosen mechanism, and if the application is authorized to act 787 on behalf of that identity for the purpose of initiating security 788 contexts, then the principal corresponding to that identity shall be 789 used, otherwise 791 3) If the platform maintains a concept of a default local identity, 792 and provides a means to map local identities into network-identities 793 for the chosen mechanism, and if the application is authorized to act 794 on behalf of the network- identity image of the default local 795 identity for the purpose of initiating security contexts using the 796 chosen mechanism, then the principal corresponding to that identity 797 shall be used, otherwise 799 4) A user-configurable default identity should be used. 801 and for the acceptor side of the context 803 1) If there is only a single authorized principal identity capable of 804 accepting security contexts for the chosen mechanism, then that 805 principal shall be used, otherwise 807 2) If the mechanism can determine the identity of the target 808 principal by examining the context-establishment token processed 809 during the accept method, and if the accepting application is 810 authorized to act as that principal for the purpose of accepting 811 security contexts using the chosen mechanism, then that principal 812 identity shall be used, otherwise 813 3) If the mechanism supports context acceptance by any principal, and 814 if mutual authentication was not requested, any principal that the 815 application is authorized to accept security contexts under using the 816 chosen mechanism may be used, otherwise 818 4) A user-configurable default identity shall be used. 820 The purpose of the above rules is to allow security contexts to be 821 established by both initiator and acceptor using the default behavior 822 whenever possible. Applications requesting default behavior are 823 likely to be more portable across mechanisms and implementations than 824 ones that instantiate an GSSCredential object representing a specific 825 identity. 827 5.9 Contexts 829 The GSSContext interface is used to represent one end of a GSS-API 830 security context, storing state information appropriate to that end 831 of the peer communication, including cryptographic state information. 832 The instantiation of the context object is done differently by the 833 initiator and the acceptor. After the context has been instantiated, 834 the initiator may choose to set various context options which will 835 determine the characteristics of the desired security context. When 836 all the application desired characteristics have been set, the 837 initiator will call the initSecContext method which will produce a 838 token for consumption by the peer's acceptSecContext method. It is 839 the responsibility of the application to deliver the authentication 840 token(s) between the peer applications for processing. Upon 841 completion of the context establishment phase, context attributes can 842 be retrieved, by both the initiator and acceptor, using the accessor 843 methods. These will reflect the actual attributes of the established 844 context. At this point the context can be used by the application to 845 apply cryptographic services to its data. 847 5.10 Authentication Tokens 849 A token is a caller-opaque type that GSS-API uses to maintain 850 synchronization between each end of the GSS-API security context. 851 The token is a cryptographically protected octet-string, generated by 852 the underlying mechanism at one end of a GSS-API security context for 853 use by the peer mechanism at the other end. Encapsulation (if 854 required) within the application protocol and transfer of the token 855 are the responsibility of the peer applications. 857 Java GSS-API uses byte arrays to represent authentication tokens. 858 Overloaded methods exist which allow the caller to supply input and 859 output streams which will be used for the reading and writing of the 860 token data. 862 5.11 Interprocess Tokens 864 Certain GSS-API routines are intended to transfer data between 865 processes in multi-process programs. These routines use a caller- 866 opaque octet-string, generated by the GSS-API in one process for use 867 by the GSS-API in another process. The calling application is 868 responsible for transferring such tokens between processes. Note 869 that, while GSS-API implementors are encouraged to avoid placing 870 sensitive information within interprocess tokens, or to 871 cryptographically protect them, many implementations will be unable 872 to avoid placing key material or other sensitive data within them. 873 It is the application's responsibility to ensure that interprocess 874 tokens are protected in transit, and transferred only to processes 875 that are trustworthy. An interprocess token is represented using a 876 byte array emitted from the export method of the GSSContext 877 interface. The receiver of the interprocess token would initialize 878 an GSSContext object with this token to create a new context. Once a 879 context has been exported, the GSSContext object is invalidated and 880 is no longer available. 882 5.12 Error Reporting 884 RFC 2743 defined the usage of major and minor status values for 885 signaling of GSS-API errors. The major code, also called GSS status 886 code, is used to signal errors at the GSS-API level independent of 887 the underlying mechanism(s). The minor status value or Mechanism 888 status code, is a mechanism defined error value indicating a 889 mechanism specific error code. 891 Java GSS-API uses exceptions implemented by the GSSException class to 892 signal both minor and major error values. Both mechanism specific 893 errors and GSS-API level errors are signaled through instances of 894 this class. The usage of exceptions replaces the need for major and 895 minor codes to be used within the API calls. GSSException class also 896 contains methods to obtain textual representations for both the major 897 and minor values, which is equivalent to the functionality of 898 gss_display_status. 900 5.12.1 GSS Status Codes 902 GSS status codes indicate errors that are independent of the 903 underlying mechanism(s) used to provide the security service. The 904 errors that can be indicated via a GSS status code are generic API 905 routine errors (errors that are defined in the GSS-API 906 specification). These bindings take advantage of the Java exceptions 907 mechanism, thus eliminating the need for calling errors. 909 A GSS status code indicates a single fatal generic API error from the 910 routine that has thrown the GSSException. Using exceptions announces 911 that a fatal error has occurred during the execution of the method. 912 The GSS-API operational model also allows for the signaling of 913 supplementary status information from the per-message calls. These 914 need to be handled as return values since using exceptions is not 915 appropriate for informatory or warning-like information. The methods 916 that are capable of producing supplementary information are the two 917 per-message methods GSSContext.verifyMIC() and GSSContext.unwrap(). 918 These methods fill the supplementary status codes in the MessageProp 919 object that was passed in. 921 A GSSException object, along with providing the functionality for 922 setting of the various error codes and translating them into textual 923 representation, also contains the definitions of all the numeric 924 error values. The following table lists the definitions of error 925 codes: 927 Table: GSS Status Codes 929 Name Value Meaning 931 BAD_BINDINGS 1 Incorrect channel bindings were 932 supplied. 934 BAD_MECH 2 An unsupported mechanism 935 was requested. 937 BAD_NAME 3 An invalid name was supplied. 939 BAD_NAMETYPE 4 A supplied name was of an 940 unsupported type. 942 BAD_STATUS 5 An invalid status code was 943 supplied. 945 BAD_MIC 6 A token had an invalid MIC. 947 CONTEXT_EXPIRED 7 The context has expired. 949 CREDENTIALS_EXPIRED 8 The referenced credentials 950 have expired. 952 DEFECTIVE_CREDENTIAL 9 A supplied credential was 953 invalid. 955 DEFECTIVE_TOKEN 10 A supplied token was invalid. 957 FAILURE 11 Miscellaneous failure, 958 unspecified at the GSS-API 959 level. 961 NO_CONTEXT 12 Invalid context has been 962 supplied. 964 NO_CRED 13 No credentials were supplied, or 965 the credentials were unavailable 966 or inaccessible. 968 BAD_QOP 14 The quality-of-protection 969 requested could not be provided. 971 UNAUTHORIZED 15 The operation is forbidden by 972 the local security policy. 974 UNAVAILABLE 16 The operation or option is 975 unavailable. 977 DUPLICATE_ELEMENT 17 The requested credential 978 element already exists. 980 NAME_NOT_MN 18 The provided name was not a 981 mechanism name. 983 The following four status codes (DUPLICATE_TOKEN, OLD_TOKEN, 984 UNSEQ_TOKEN, and GAP_TOKEN) are contained in a GSSException 985 only if detected during context establishment, in which case it 986 is a fatal error. (During per-message calls, these values are 987 indicated as supplementary information contained in the 988 MessageProp object.) They are: 990 DUPLICATE_TOKEN 19 The token was a duplicate of an 991 earlier version. 993 OLD_TOKEN 20 The token's validity period has 994 expired. 996 UNSEQ_TOKEN 21 A later token has already been 997 processed. 999 GAP_TOKEN 22 The expected token was not 1000 received. 1002 The GSS major status code of FAILURE is used to indicate that the 1003 underlying mechanism detected an error for which no specific GSS 1004 status code is defined. The mechanism-specific status code can 1005 provide more details about the error. 1007 The different major status codes that can be contained in the 1008 GSSException object thrown by the methods in this specification are 1009 the same as the major status codes returned by the corresponding 1010 calls in RFC 2743 [GSSAPIv2-UPDATE]. 1012 5.12.2 Mechanism-Specific Status Codes 1014 Mechanism-specific status codes are communicated in two ways, they 1015 are part of any GSSException thrown from the mechanism specific layer 1016 to signal a fatal error, or they are part of the MessageProp object 1017 that the per-message calls use to signal non-fatal errors. 1019 A default value of 0 in either the GSSException object or the 1020 MessageProp object will be used to represent the absence of any 1021 mechanism specific status code. 1023 5.12.3 Supplementary Status Codes 1025 Supplementary status codes are confined to the per-message methods of 1026 the GSSContext interface. Because of the informative nature of these 1027 errors it is not appropriate to use exceptions to signal them. 1028 Instead, the per-message operations of the GSSContext interface 1029 return these values in a MessageProp object. 1031 The MessageProp class defines query methods which return boolean 1032 values indicating the following supplementary states: 1034 Table: Supplementary Status Methods 1036 Method Name Meaning when "true" is returned 1038 isDuplicateToken The token was a duplicate of an 1039 earlier token. 1041 isOldToken The token's validity period has 1042 expired. 1044 isUnseqToken A later token has already been 1045 processed. 1047 isGapToken An expected per-message token was 1048 not received. 1050 "true" return value for any of the above methods indicates that the 1051 token exhibited the specified property. The application must 1052 determine the appropriate course of action for these supplementary 1053 values. They are not treated as errors by the GSS-API. 1055 5.13 Names 1057 A name is used to identify a person or entity. GSS-API authenticates 1058 the relationship between a name and the entity claiming the name. 1060 Since different authentication mechanisms may employ different 1061 namespaces for identifying their principals, GSS-API's naming support 1062 is necessarily complex in multi-mechanism environments (or even in 1063 some single-mechanism environments where the underlying mechanism 1064 supports multiple namespaces). 1066 Two distinct conceptual representations are defined for names: 1068 1) A GSS-API form represented by implementations of the GSSName 1069 interface: A single GSSName object may contain multiple names from 1070 different namespaces, but all names should refer to the same entity. 1071 An example of such an internal name would be the name returned from a 1072 call to the getName method of the GSSCredential interface, when 1073 applied to a credential containing credential elements for multiple 1074 authentication mechanisms employing different namespaces. This 1075 GSSName object will contain a distinct name for the entity for each 1076 authentication mechanism. 1078 For GSS-API implementations supporting multiple namespaces, GSSName 1079 implementations must contain sufficient information to determine the 1080 namespace to which each primitive name belongs. 1082 2) Mechanism-specific contiguous byte array and string forms: 1083 Different GSSName initialization methods are provided to handle both 1084 byte array and string formats and to accommodate various calling 1085 applications and name types. These formats are capable of containing 1086 only a single name (from a single namespace). Contiguous string 1087 names are always accompanied by an object identifier specifying the 1088 namespace to which the name belongs, and their format is dependent on 1089 the authentication mechanism that employs that name. The string name 1090 forms are assumed to be printable, and may therefore be used by GSS- 1091 API applications for communication with their users. The byte array 1092 name formats are assumed to be in non-printable formats (e.g. the 1093 byte array returned from the export method of the GSSName interface). 1095 A GSSName object can be converted to a contiguous representation by 1096 using the toString method. This will guarantee that the name will be 1097 converted to a printable format. Different initialization methods in 1098 the GSSName interface are defined allowing support for multiple 1099 syntaxes for each supported namespace, and allowing users the freedom 1100 to choose a preferred name representation. The toString method 1101 should use an implementation-chosen printable syntax for each 1102 supported name-type. To obtain the printable name type, 1103 getStringNameType method can be used. 1105 There is no guarantee that calling the toString method on the GSSName 1106 interface will produce the same string form as the original imported 1107 string name. Furthermore, it is possible that the name was not even 1108 constructed from a string representation. The same applies to name- 1109 space identifiers which may not necessarily survive unchanged after a 1110 journey through the internal name-form. An example of this might be 1111 a mechanism that authenticates X.500 names, but provides an 1112 algorithmic mapping of Internet DNS names into X.500. That 1113 mechanism's implementation of GSSName might, when presented with a 1114 DNS name, generate an internal name that contained both the original 1115 DNS name and the equivalent X.500 name. Alternatively, it might only 1116 store the X.500 name. In the latter case, the toString method of 1117 GSSName would most likely generate a printable X.500 name, rather 1118 than the original DNS name. 1120 The context acceptor can obtain a GSSName object representing the 1121 entity performing the context initiation (through the usage of 1122 getSrcName method). Since this name has been authenticated by a 1123 single mechanism, it contains only a single name (even if the 1124 internal name presented by the context initiator to the GSSContext 1125 object had multiple components). Such names are termed internal 1126 mechanism names, or "MN"s and the names emitted by GSSContext 1127 interface in the getSrcName and getTargName are always of this type. 1128 Since some applications may require MNs without wanting to incur the 1129 overhead of an authentication operation, creation methods are 1130 provided that take not only the name buffer and name type, but also 1131 the mechanism oid for which this name should be created. When 1132 dealing with an existing GSSName object, the canonicalize method may 1133 be invoked to convert a general internal name into an MN. 1135 GSSName objects can be compared using their equal method, which 1136 returns "true" if the two names being compared refer to the same 1137 entity. This is the preferred way to perform name comparisons 1138 instead of using the printable names that a given GSS-API 1139 implementation may support. Since GSS-API assumes that all primitive 1140 names contained within a given internal name refer to the same 1141 entity, equal can return "true" if the two names have at least one 1142 primitive name in common. If the implementation embodies knowledge 1143 of equivalence relationships between names taken from different 1144 namespaces, this knowledge may also allow successful comparisons of 1145 internal names containing no overlapping primitive elements. 1147 When used in large access control lists, the overhead of creating an 1148 GSSName object on each name and invoking the equal method on each 1149 name from the ACL may be prohibitive. As an alternative way of 1150 supporting this case, GSS-API defines a special form of the 1151 contiguous byte array name which may be compared directly (byte by 1152 byte). Contiguous names suitable for comparison are generated by the 1153 export method. Exported names may be re-imported by using the byte 1154 array constructor and specifying the NT_EXPORT_NAME as the name type 1155 object identifier. The resulting GSSName name will also be a MN. 1156 The GSSName interface defines public static Oid objects representing 1157 the standard name types. Structurally, an exported name object 1158 consists of a header containing an OID identifying the mechanism that 1159 authenticated the name, and a trailer containing the name itself, 1160 where the syntax of the trailer is defined by the individual 1161 mechanism specification. Detailed description of the format is 1162 specified in the language-independent GSS-API specification 1163 [GSSAPIv2-UPDATE]. 1165 Note that the results obtained by using the equals method will in 1166 general be different from those obtained by invoking canonicalize and 1167 export, and then comparing the byte array output. The first series 1168 of operation determines whether two (unauthenticated) names identify 1169 the same principal; the second whether a particular mechanism would 1170 authenticate them as the same principal. These two operations will 1171 in general give the same results only for MNs. 1173 It is important to note that the above are guidelines as how GSSName 1174 implementations should behave, and are not intended to be specific 1175 requirements of how names objects must be implemented. The mechanism 1176 designers are free to decide on the details of their implementations 1177 of the GSSName interface as long as the behavior satisfies the above 1178 guidelines. 1180 5.14 Channel Bindings 1182 GSS-API supports the use of user-specified tags to identify a given 1183 context to the peer application. These tags are intended to be used 1184 to identify the particular communications channel that carries the 1185 context. Channel bindings are communicated to the GSS-API using the 1186 ChannelBinding object. The application may use byte arrays to 1187 specify the application data to be used in the channel binding as 1188 well as using instances of the InetAddress. The InetAddress for the 1189 initiator and/or acceptor can be used within an instance of a 1190 ChannelBinding. ChannelBinding can be set for the GSSContext object 1191 using the setChannelBinding method before the first call to init or 1192 accept has been performed. Unless the setChannelBinding method has 1193 been used to set the ChannelBinding for a GSSContext object, "null" 1194 ChannelBinding will be assumed. InetAddress is currently the only 1195 address type defined within the Java platform and as such, it is the 1196 only one supported within the ChannelBinding class. Applications 1197 that use other types of addresses can include them as part of the 1198 application specific data. 1200 Conceptually, the GSS-API concatenates the initiator and acceptor 1201 address information, and the application supplied byte array to form 1202 an octet string. The mechanism calculates a MIC over this octet 1203 string and binds the MIC to the context establishment token emitted 1204 by init method of the GSSContext interface. The same bindings are 1205 set by the context acceptor for its GSSContext object and during 1206 processing of the accept method a MIC is calculated in the same way. 1207 The calculated MIC is compared with that found in the token, and if 1208 the MICs differ, accept will throw a GSSException with the major code 1209 set to BAD_BINDINGS, and the context will not be established. Some 1210 mechanisms may include the actual channel binding data in the token 1211 (rather than just a MIC); applications should therefore not use 1212 confidential data as channel-binding components. 1214 Individual mechanisms may impose additional constraints on addresses 1215 that may appear in channel bindings. For example, a mechanism may 1216 verify that the initiator address field of the channel binding 1217 contains the correct network address of the host system. Portable 1218 applications should therefore ensure that they either provide correct 1219 information for the address fields, or omit setting of the addressing 1220 information. 1222 5.15 Stream Objects 1224 The context object provides overloaded methods which use input and 1225 output streams as the means to convey authentication and per-message 1226 GSS-API tokens. It is important to note that the streams are 1227 expected to contain the usual GSS-API tokens which would otherwise be 1228 handled through the usage of byte arrays. The tokens are expected to 1229 have a definite start and an end. The callers are responsible for 1230 ensuring that the supplied streams will not block, or expect to block 1231 until a full token is processed by the GSS-API method. Only a single 1232 GSS-API token will be processed per invocation of the stream based 1233 method. 1235 The usage of streams allows the callers to have control and 1236 management of the supplied buffers. Because streams are non- 1237 primitive objects, the callers can make the streams as complicated or 1238 as simple as desired simply by using the streams defined in the 1239 java.io package or creating their own through the use of inheritance. 1240 This will allow for the application's greatest flexibility. 1242 5.16 Optional Parameters 1244 Whenever the application wishes to omit an optional parameter the 1245 "null" value shall be used. The detailed method descriptions 1246 indicate which parameters are optional. Methods overloading has also 1247 been used as a technique to indicate default parameters. 1249 6. Introduction to GSS-API Classes and Interfaces 1251 This section presents a brief description of the classes and 1252 interfaces that constitute the GSS-API. The implementations of these 1253 are obtained from the CLASSPATH defined by the application. If Java 1254 GSS becomes part of the standard Java API's then these classes will 1255 be available by default on all systems as part of the JRE's system 1256 classes. 1258 This section also shows the corresponding RFC 2743 functionality 1259 implemented by each of the classes. Detailed description of these 1260 classes and their methods is presented in section 7. 1262 6.1 GSSManager class 1264 This abstract class serves as a factory to instantiate 1265 implementations of the GSS-API interfaces and also provides methods 1266 to make queries about underlying security mechanisms. 1268 A default implementation can be obtained using the static method 1269 getInstance(). Applications that desire to provide their own 1270 implementation of the GSSManager class can simply extend the abstract 1271 class themselves. 1273 This class contains equivalents of the following RFC 2743 routines: 1275 gss_import_name Create an internal name from 7.1.6- 1276 the supplied information. 7.1.9 1278 gss_acquire_cred Acquire credential 7.1.10- 1279 for use. 7.1.12 1281 gss_import_sec_context Create a previously exported 7.1.15 1282 context. 1284 gss_indicate_mechs List the mechanisms 7.1.3 1285 supported by this GSS-API 1286 implementation. 1288 gss_inquire_mechs_for_name List the mechanisms 7.1.5 1289 supporting the 1290 specified name type. 1292 gss_inquire_names_for_mech List the name types 7.1.4 1293 supported by the 1294 specified mechanism. 1296 Figure 3 1298 6.2 GSSName interface 1300 GSS-API names are represented in the Java bindings through the 1301 GSSName interface. Different name formats and their definitions are 1302 identified with universal Object Identifiers (oids). The format of 1303 the names can be derived based on the unique oid of each name type. 1304 The following GSS-API routines are provided by the GSSName interface: 1306 RFC 2743 Routine Function Section(s) 1308 gss_display_name Covert internal name 7.2.7 1309 representation to text format. 1311 gss_compare_name Compare two internal names. 7.2.3, 1312 7.2.4 1314 gss_release_name Release resources associated N/A 1315 with the internal name. 1317 gss_canonicalize_name Convert an internal name to a 7.2.5 1318 mechanism name. 1320 gss_export_name Convert a mechanism name to 7.2.6 1321 export format. 1323 gss_duplicate_name Create a copy of the internal N/A 1324 name. 1326 Figure 4 1328 The gss_release_name call is not provided as Java does its own 1329 garbage collection. The gss_duplicate_name call is also redundant; 1330 the GSSName interface has no mutator methods that can change the 1331 state of the object so it is safe for sharing. 1333 6.3 GSSCredential interface 1335 The GSSCredential interface is responsible for the encapsulation of 1336 GSS-API credentials. Credentials identify a single entity and 1337 provide the necessary cryptographic information to enable the 1338 creation of a context on behalf of that entity. A single credential 1339 may contain multiple mechanism specific credentials, each referred to 1340 as a credential element. The GSSCredential interface provides the 1341 functionality of the following GSS-API routines: 1343 RFC 2743 Routine Function Section(s) 1345 gss_add_cred Constructs credentials 7.3.12 1346 incrementally. 1348 gss_inquire_cred Obtain information about 7.3.4- 1349 credential. 7.3.11 1351 gss_inquire_cred_by_mech Obtain per-mechanism 7.3.5- 1352 information about 7.3.10 1353 a credential. 1355 gss_release_cred Disposes of credentials 7.3.3 1356 after use. 1358 Figure 5 1360 6.4 GSSContext interface 1362 This interface encapsulates the functionality of context-level calls 1363 required for security context establishment and management between 1364 peers as well as the per-message services offered to applications. A 1365 context is established between a pair of peers and allows the usage 1366 of security services on a per-message basis on application data. It 1367 is created over a single security mechanism. The GSSContext 1368 interface provides the functionality of the following GSS-API 1369 routines: 1371 RFC 2743 Routine Function Section(s) 1373 gss_init_sec_context Initiate the creation of a 7.4.3- 1374 security context with a peer. 7.4.6 1376 gss_accept_sec_context Accept a security context 7.4.7- 1377 initiated by a peer. 7.4.10 1379 gss_delete_sec_context Destroy a security context. 7.4.12 1381 gss_context_time Obtain remaining context 7.4.41 1382 time. 1384 gss_inquire_context Obtain context 7.4.32- 1385 characteristics. 7.3.46 1387 gss_wrap_size_limit Determine token-size limit 7.4.13 1388 for gss_wrap. 1390 gss_export_sec_context Transfer security context 7.4.22 1391 to another process. 1393 gss_get_mic Calculate a cryptographic 7.4.18, 1394 Message Integrity Code (MIC) 7.4.19 1395 for a message. 1397 gss_verify_mic Verify integrity on a received 7.4.20, 1398 message. 7.4.21 1400 gss_wrap Attach a MIC to a message and 7.4.14, 1401 optionally encrypt the message 7.4.15 1402 content. 1404 gss_unwrap Obtain a previously wrapped 7.4.16, 1405 application message verifying 7.4.17 1406 its integrity and optionally 1407 decrypting it. 1409 Figure 6 1411 The functionality offered by the gss_process_context_token routine 1412 has not been included in the Java bindings specification. The 1413 corresponding functionality of gss_delete_sec_context has also been 1414 modified to not return any peer tokens. This has been proposed in 1415 accordance to the recommendations stated in RFC 2743. GSSContext 1416 does offer the functionality of destroying the locally-stored context 1417 information. 1419 6.5 MessageProp class 1421 This helper class is used in the per-message operations on the 1422 context. An instance of this class is created by the application and 1423 then passed into the per-message calls. In some cases, the 1424 application conveys information to the GSS-API implementation through 1425 this object and in other cases the GSS-API returns information to the 1426 application by setting it in this object. See the description of the 1427 per-message operations wrap, unwrap, getMIC, and verifyMIC in the 1428 GSSContext interfaces for details. 1430 6.6 GSSException class 1432 Exceptions are used in the Java bindings to signal fatal errors to 1433 the calling applications. This replaces the major and minor codes 1434 used in the C-bindings specification as a method of signaling 1435 failures. The GSSException class handles both minor and major codes, 1436 as well as their translation into textual representation. All GSS- 1437 API methods are declared as throwing this exception. 1439 RFC 2743 Routine Function Section 1441 gss_display_status Retrieve textual 7.8.5, 7.8.6, 1442 representation of error 7.8.8, 7.8.9 1443 codes. 1445 Figure 7 1447 6.7 Oid class 1449 This utility class is used to represent Universal Object Identifiers 1450 and their associated operations. GSS-API uses object identifiers to 1451 distinguish between security mechanisms and name types. This class, 1452 aside from being used whenever an object identifier is needed, 1453 implements the following GSS-API functionality: 1455 RFC 2743 Routine Function Section 1457 gss_test_oid_set_member Determine if the specified oid 7.7.5 1458 is part of a set of oids. 1460 Figure 8 1462 6.8 ChannelBinding class 1464 An instance of this class is used to specify channel binding 1465 information to the GSSContext object before the start of a security 1466 context establishment. The application may use a byte array to 1467 specify application data to be used in the channel binding as well as 1468 use instances of the InetAddress. InetAddress is currently the only 1469 address type defined within the Java platform and as such, it is the 1470 only one supported within the ChannelBinding class. Applications 1471 that use other types of addresses can include them as part of the 1472 application data. 1474 7. Detailed GSS-API Class Description 1476 This section lists a detailed description of all the public methods 1477 that each of the GSS-API classes and interfaces must provide. 1479 7.1 public abstract class GSSManager 1481 The GSSManager class is an abstract class that serves as a factory 1482 for three GSS interfaces: GSSName, GSSCredential, and GSSContext. It 1483 also provides methods for applications to determine what mechanisms 1484 are available from the GSS implementation and what nametypes these 1485 mechanisms support. An instance of the default GSSManager subclass 1486 may be obtained through the static method getInstance(), but 1487 applications are free to instantiate other subclasses of GSSManager. 1489 All but one method in this class are declared abstract. This means 1490 that subclasses have to provide the complete implementation for those 1491 methods. The only exception to this is the static method 1492 getInstance() which will have platform specific code to return an 1493 instance of the default subclass. 1495 Platform providers of GSS are required not to add any constructors to 1496 this class, private, public, or protected. This will ensure that all 1497 subclasses invoke only the default constructor provided to the base 1498 class by the compiler. 1500 A subclass extending the GSSManager abstract class may be implemented 1501 as a modular provider based layer that utilizes some well known 1502 service provider specification. The GSSManager API provides the 1503 application with methods to set provider preferences on such an 1504 implementation. These methods also allow the implementation to throw 1505 a well-defined exception in case provider based configuration is not 1506 supported. Applications that expect to be portable should be aware 1507 of this and recover cleanly by catching the exception. 1509 It is envisioned that there will be three most common ways in which 1510 providers will be used: 1512 1) The application does not care about what provider is used (the 1513 default case). 1515 2) The application wants a particular provider to be used 1516 preferentially, either for a particular mechanism or all the time, 1517 irrespective of mechanism. 1519 3) The application wants to use the locally configured providers as 1520 far as possible but if support is missing for one or more mechanisms 1521 then it wants to fall back on its own provider. 1523 The GSSManager class has two methods that enable these modes of 1524 usage: addProviderAtFront() and addProviderAtEnd(). These methods 1525 have the effect of creating an ordered list of pairs 1526 where each pair indicates a preference of provider for a given oid. 1528 The use of these methods does not require any knowledge of whatever 1529 service provider specification the GSSManager subclass follows. It 1530 is hoped that these methods will serve the needs of most 1531 applications. Additional methods may be added to an extended 1532 GSSManager that could be part of a service provider specification 1533 that is standardized later. 1535 7.1.1 Example Code 1537 GSSManager mgr = GSSManager.getInstance(); 1539 // What mechs are available to us? 1540 Oid[] supportedMechs = mgr.getMechs(); 1542 // Set a preference for the provider to be used when support 1543 // is needed for the mechanisms: 1544 // "1.2.840.113554.1.2.2" and "1.3.6.1.5.5.1.1". 1546 Oid krb = new Oid("1.2.840.113554.1.2.2"); 1547 Oid spkm1 = new Oid("1.3.6.1.5.5.1.1"); 1549 Provider p = (Provider) (new com.foo.security.Provider()); 1551 mgr.addProviderAtFront(p, krb); 1552 mgr.addProviderAtFront(p, spkm1); 1554 // What name types does this spkm implementation support? 1555 Oid[] nameTypes = mgr.getNamesForMech(spkm1); 1557 Figure 9 1559 7.1.2 getInstance 1561 public static GSSManager getInstance() 1563 Returns the default GSSManager implementation. 1565 7.1.3 getMechs 1567 public abstract Oid[] getMechs() 1569 Returns an array of Oid objects indicating the mechanisms available 1570 to GSS-API callers. A "null" value is returned when no mechanism are 1571 available (an example of this would be when mechanism are dynamically 1572 configured, and currently no mechanisms are installed). 1574 7.1.4 getNamesForMech 1576 public abstract Oid[] getNamesForMech(Oid mech) 1577 throws GSSException 1579 Returns name type Oid's supported by the specified mechanism. 1581 Parameters: 1583 mech The Oid object for the mechanism to query. 1585 7.1.5 getMechsForName 1587 public abstract Oid[] getMechsForName(Oid nameType) 1589 Returns an array of Oid objects corresponding to the mechanisms that 1590 support the specific name type. "null" is returned when no mechanisms 1591 are found to support the specified name type. 1593 Parameters: 1595 nameType The Oid object for the name type. 1597 7.1.6 createName 1599 public abstract GSSName createName(String nameStr, Oid nameType) 1600 throws GSSException 1602 Factory method to convert a contiguous string name from the specified 1603 namespace to a GSSName object. In general, the GSSName object 1604 created will not be an MN; two examples that are exceptions to this 1605 are when the namespace type parameter indicates NT_EXPORT_NAME or 1606 when the GSS-API implementation is not multi-mechanism. 1608 Parameters: 1610 nameStr The string representing a printable form of the name to 1611 create. 1613 nameType The Oid specifying the namespace of the printable name 1614 supplied. Note that nameType serves to describe and qualify the 1615 interpretation of the input nameStr, it does not necessarily imply 1616 a type for the output GSSName implementation. "null" value can be 1617 used to specify that a mechanism specific default printable syntax 1618 should be assumed by each mechanism that examines nameStr. 1620 7.1.7 createName 1622 public abstract GSSName createName(byte[] name, Oid nameType) 1623 throws GSSException 1625 Factory method to convert a contiguous byte array containing a name 1626 from the specified namespace to a GSSName object. In general, the 1627 GSSName object created will not be an MN; two examples that are 1628 exceptions to this are when the namespace type parameter indicates 1629 NT_EXPORT_NAME or when the GSS-API implementation is not multi- 1630 mechanism. 1632 Parameters: 1634 name The byte array containing the name to create. 1636 nameType The Oid specifying the namespace of the name supplied 1637 in the byte array. Note that nameType serves to describe and 1638 qualify the interpretation of the input name byte array, it does 1639 not necessarily imply a type for the output GSSName 1640 implementation. "null" value can be used to specify that a 1641 mechanism specific default syntax should be assumed by each 1642 mechanism that examines the byte array. 1644 7.1.8 createName 1646 public abstract GSSName createName(String nameStr, Oid nameType, 1647 Oid mech) throws GSSException 1649 Factory method to convert a contiguous string name from the specified 1650 namespace to an GSSName object that is a mechanism name (MN). In 1651 other words, this method is a utility that does the equivalent of two 1652 steps: the createName described in 7.1.6 and then also the 1653 GSSName.canonicalize() described in 7.2.5. 1655 Parameters: 1657 nameStr The string representing a printable form of the name to 1658 create. 1660 nameType The Oid specifying the namespace of the printable name 1661 supplied. Note that nameType serves to describe and qualify the 1662 interpretation of the input nameStr, it does not necessarily imply 1663 a type for the output GSSName implementation. "null" value can be 1664 used to specify that a mechanism specific default printable syntax 1665 should be assumed when the mechanism examines nameStr. 1667 mech Oid specifying the mechanism for which this name should 1668 be created. 1670 7.1.9 createName 1672 public abstract GSSName createName(byte[] name, Oid nameType, 1673 Oid mech) throws GSSException 1675 Factory method to convert a contiguous byte array containing a name 1676 from the specified namespace to a GSSName object that is an MN. In 1677 other words, this method is a utility that does the equivalent of two 1678 steps: the createName described in 7.1.7 and then also the 1679 GSSName.canonicalize() described in 7.2.5. 1681 Parameters: 1683 name The byte array representing the name to create. 1685 nameType The Oid specifying the namespace of the name supplied in 1686 the byte array. Note that nameType serves to describe and qualify 1687 the interpretation of the input name byte array, it does not 1688 necessarily imply a type for the output GSSName implementation. 1689 "null" value can be used to specify that a mechanism specific 1690 default syntax should be assumed by each mechanism that examines 1691 the byte array. 1693 mech Oid specifying the mechanism for which this name should 1694 be created. 1696 7.1.10 createCredential 1698 public abstract GSSCredential createCredential(int usage) 1699 throws GSSException 1701 Factory method for acquiring default credentials. This will cause 1702 the GSS-API to use system specific defaults for the set of 1703 mechanisms, name, and a DEFAULT lifetime. 1705 Parameters: 1707 usage The intended usage for this credential object.The value 1708 of this parameter must be one of: 1709 GSSCredential.INITIATE_AND_ACCEPT(0), 1710 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1712 7.1.11 createCredential 1714 public abstract GSSCredential createCredential(GSSName aName, 1715 int lifetime, Oid mech, int usage) 1716 throws GSSException 1718 Factory method for acquiring a single mechanism credential. 1720 Parameters: 1722 aName Name of the principal for whom this credential is to be 1723 acquired. Use "null" to specify the default principal. 1725 lifetime The number of seconds that credentials should remain 1726 valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the 1727 credentials have the maximum permitted lifetime. Use 1728 GSSCredential.DEFAULT_LIFETIME to request default credential 1729 lifetime. 1731 mech The oid of the desired mechanism. Use "(Oid) null" to 1732 request the default mechanism(s). 1734 usage The intended usage for this credential object. The 1735 value of this parameter must be one of: 1736 GSSCredential.INITIATE_AND_ACCEPT(0), 1737 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1739 7.1.12 createCredential 1741 public abstract GSSCredential createCredential(GSSName aName, 1742 int lifetime, Oid[] mechs, int usage) 1743 throws GSSException 1745 Factory method for acquiring credentials over a set of mechanisms. 1746 Acquires credentials for each of the mechanisms specified in the 1747 array called mechs. To determine the list of mechanisms' for which 1748 the acquisition of credentials succeeded, the caller should use the 1749 GSSCredential.getMechs() method. 1751 Parameters: 1753 aName Name of the principal for whom this credential is to be 1754 acquired. Use "null" to specify the default principal. 1756 lifetime The number of seconds that credentials should remain 1757 valid. Use GSSCredential.INDEFINITE_LIFETIME to request that the 1758 credentials have the maximum permitted lifetime. Use 1759 GSSCredential.DEFAULT_LIFETIME to request default credential 1760 lifetime. 1762 mechs The array of mechanisms over which the credential is to 1763 be acquired. Use "(Oid[]) null" for requesting a system specific 1764 default set of mechanisms. 1766 usage The intended usage for this credential object. The 1767 value of this parameter must be one of: 1768 GSSCredential.INITIATE_AND_ACCEPT(0), 1769 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 1771 7.1.13 createContext 1773 public abstract GSSContext createContext(GSSName peer, Oid mech, 1774 GSSCredential myCred, int lifetime) 1775 throws GSSException 1777 Factory method for creating a context on the initiator's side. 1778 Context flags may be modified through the mutator methods prior to 1779 calling GSSContext.initSecContext(). 1781 Parameters: 1783 peer Name of the target peer. 1785 mech Oid of the desired mechanism. Use "(Oid) null" to 1786 request the default mechanism. 1788 myCred Credentials of the initiator. Use "null" to act as a 1789 default initiator principal. 1791 lifetime The request lifetime, in seconds, for the context. Use 1792 GSSContext.INDEFINITE_LIFETIME and GSSContext.DEFAULT_LIFETIME to 1793 request indefinite or default context lifetime. 1795 7.1.14 createContext 1797 public abstract GSSContext createContext(GSSCredential myCred) 1798 throws GSSException 1800 Factory method for creating a context on the acceptor' side. The 1801 context's properties will be determined from the input token supplied 1802 to the accept method. 1804 Parameters: 1806 myCred Credentials for the acceptor. Use "null" to act as a 1807 default acceptor principal. 1809 7.1.15 createContext 1811 public abstract GSSContext createContext(byte[] interProcessToken) 1812 throws GSSException 1814 Factory method for creating a previously exported context. The 1815 context properties will be determined from the input token and can't 1816 be modified through the set methods. 1818 Parameters: 1820 interProcessToken The token previously emitted from the export 1821 method. 1823 7.1.16 addProviderAtFront 1825 public abstract void addProviderAtFront(Provider p, Oid mech) 1826 throws GSSException 1828 This method is used to indicate to the GSSManager that the 1829 application would like a particular provider to be used ahead of all 1830 others when support is desired for the given mechanism. When a value 1831 of null is used instead of an Oid for the mechanism, the GSSManager 1832 must use the indicated provider ahead of all others no matter what 1833 the mechanism is. Only when the indicated provider does not support 1834 the needed mechanism should the GSSManager move on to a different 1835 provider. 1837 Calling this method repeatedly preserves the older settings but 1838 lowers them in preference thus forming an ordered list of provider 1839 and Oid pairs that grows at the top. 1841 Calling addProviderAtFront with a null Oid will remove all previous 1842 preferences that were set for this provider in the GSSManager 1843 instance. Calling addProviderAtFront with a non-null Oid will remove 1844 any previous preference that was set using this mechanism and this 1845 provider together. 1847 If the GSSManager implementation does not support an SPI with a 1848 pluggable provider architecture it should throw a GSSException with 1849 the status code GSSException.UNAVAILABLE to indicate that the 1850 operation is unavailable. 1852 Parameters: 1854 p The provider instance that should be used whenever 1855 support is needed for mech. 1857 mech The mechanism for which the provider is being set 1859 7.1.17 Example Code 1861 Suppose an application desired that the provider A always be checked 1862 first when any mechanism is needed, it would call: 1864 GSSManager mgr = GSSManager.getInstance(); 1865 // mgr may at this point have its own pre-configured list 1866 // of provider preferences. The following will prepend to 1867 // any such list: 1869 mgr.addProviderAtFront(A, null); 1871 Now if it also desired that the mechanism of Oid m1 always be 1872 obtained from the provider B before the previously set A was checked, 1873 it would call: 1875 mgr.addProviderAtFront(B, m1); 1877 The GSSManager would then first check with B if m1 was needed. In 1878 case B did not provide support for m1, the GSSManager would continue 1879 on to check with A. If any mechanism m2 is needed where m2 is 1880 different from m1 then the GSSManager would skip B and check with A 1881 directly. 1883 Suppose at a later time the following call is made to the same 1884 GSSManager instance: 1886 mgr.addProviderAtFront(B, null) 1888 then the previous setting with the pair (B, m1) is subsumed by this 1889 and should be removed. Effectively the list of preferences now 1890 becomes {(B, null), (A, null), ... //followed by the pre-configured 1891 list. 1893 Please note, however, that the following call: 1895 mgr.addProviderAtFront(A, m3) 1897 does not subsume the previous setting of (A, null) and the list will 1898 effectively become {(A, m3), (B, null), (A, null), ...} 1900 7.1.18 addProviderAtEnd 1902 public abstract void addProviderAtEnd(Provider p, Oid mech) 1903 throws GSSException 1905 This method is used to indicate to the GSSManager that the 1906 application would like a particular provider to be used if no other 1907 provider can be found that supports the given mechanism. When a 1908 value of null is used instead of an Oid for the mechanism, the 1909 GSSManager must use the indicated provider for any mechanism. 1911 Calling this method repeatedly preserves the older settings but 1912 raises them above newer ones in preference thus forming an ordered 1913 list of providers and Oid pairs that grows at the bottom. Thus the 1914 older provider settings will be utilized first before this one is. 1916 If there are any previously existing preferences that conflict with 1917 the preference being set here, then the GSSManager should ignore this 1918 request. 1920 If the GSSManager implementation does not support an SPI with a 1921 pluggable provider architecture it should throw a GSSException with 1922 the status code GSSException.UNAVAILABLE to indicate that the 1923 operation is unavailable. 1925 Parameters: 1927 p The provider instance that should be used whenever 1928 support is needed for mech. 1930 mech The mechanism for which the provider is being set 1932 7.1.19 Example Code 1934 Suppose an application desired that when a mechanism of Oid m1 is 1935 needed the system default providers always be checked first, and only 1936 when they do not support m1 should a provider A be checked. It would 1937 then make the call: 1939 GSSManager mgr = GSSManager.getInstance(); 1941 mgr.addProviderAtEnd(A, m1); 1943 Now, if it also desired that for all mechanisms the provider B be 1944 checked after all configured providers have been checked, it would 1945 then call: 1947 mgr.addProviderAtEnd(B, null); 1949 Effectively the list of preferences now becomes {..., (A, m1), (B, 1950 null)}. 1952 Suppose at a later time the following call is made to the same 1953 GSSManager instance: 1955 mgr.addProviderAtEnd(B, m2) 1957 then the previous setting with the pair (B, null) subsumes this and 1958 therefore this request should be ignored. The same would happen if a 1959 request is made for the already existing pairs of (A, m1) or (B, 1960 null). 1962 Please note, however, that the following call: 1964 mgr.addProviderAtEnd(A, null) 1966 is not subsumed by the previous setting of (A, m1) and the list will 1967 effectively become {..., (A, m1), (B, null), (A, null)} 1969 7.2 public interface GSSName 1971 This interface encapsulates a single GSS-API principal entity. 1972 Different name formats and their definitions are identified with 1973 universal Object Identifiers (Oids). The format of the names can be 1974 derived based on the unique oid of its namespace type. 1976 7.2.1 Example Code 1978 Included below are code examples utilizing the GSSName interface. 1979 The code below creates a GSSName, converts it to a mechanism name 1980 (MN), performs a comparison, obtains a printable representation of 1981 the name, exports it and then re-imports to obtain a new GSSName. 1983 GSSManager mgr = GSSManager.getInstance(); 1985 // create a host based service name 1986 GSSName name = mgr.createName("service@host", 1987 GSSName.NT_HOSTBASED_SERVICE); 1989 Oid krb5 = new Oid("1.2.840.113554.1.2.2"); 1991 GSSName mechName = name.canonicalize(krb5); 1993 // the above two steps are equivalent to the following 1994 GSSName mechName = mgr.createName("service@host", 1995 GSSName.NT_HOSTBASED_SERVICE, krb5); 1997 // perform name comparison 1998 if (name.equals(mechName)) 1999 print("Names are equals."); 2001 // obtain textual representation of name and its printable 2002 // name type 2003 print(mechName.toString() + 2004 mechName.getStringNameType().toString()); 2006 // export and re-import the name 2007 byte[] exportName = mechName.export(); 2009 // create a new name object from the exported buffer 2010 GSSName newName = mgr.createName(exportName, 2011 GSSName.NT_EXPORT_NAME); 2013 7.2.2 Static Constants 2015 public static final Oid NT_HOSTBASED_SERVICE 2017 Oid indicating a host-based service name form. It is used to 2018 represent services associated with host computers. This name form is 2019 constructed using two elements, "service" and "hostname", as follows: 2021 service@hostname 2023 Values for the "service" element are registered with the IANA. It 2024 represents the following value: { iso(1) member-body(2) Unites 2025 States(840) mit(113554) infosys(1) gssapi(2) generic(1) 2026 service_name(4) } 2028 public static final Oid NT_USER_NAME 2029 Name type to indicate a named user on a local system. It represents 2030 the following value: { iso(1) member-body(2) United States(840) 2031 mit(113554) infosys(1) gssapi(2) generic(1) user_name(1) } 2033 public static final Oid NT_MACHINE_UID_NAME 2035 Name type to indicate a numeric user identifier corresponding to a 2036 user on a local system. (e.g. Uid). It represents the following 2037 value: { iso(1) member-body(2) United States(840) mit(113554) 2038 infosys(1) gssapi(2) generic(1) machine_uid_name(2) } 2040 public static final Oid NT_STRING_UID_NAME 2042 Name type to indicate a string of digits representing the numeric 2043 user identifier of a user on a local system. It represents the 2044 following value: { iso(1) member-body(2) United States(840) 2045 mit(113554) infosys(1) gssapi(2) generic(1) string_uid_name(3) } 2047 public static final Oid NT_ANONYMOUS 2049 Name type for representing an anonymous entity. It represents the 2050 following value: { 1(iso), 3(org), 6(dod), 1(internet), 5(security), 2051 6(nametypes), 3(gss-anonymous-name) } 2053 public static final Oid NT_EXPORT_NAME 2055 Name type used to indicate an exported name produced by the export 2056 method. It represents the following value: { 1(iso), 3(org), 6(dod), 2057 1(internet), 5(security), 6(nametypes), 4(gss-api-exported-name) } 2059 7.2.3 equals 2061 public boolean equals(GSSName another) throws GSSException 2063 Compares two GSSName objects to determine whether they refer to the 2064 same entity. This method may throw a GSSException when the names 2065 cannot be compared. If either of the names represents an anonymous 2066 entity, the method will return "false". 2068 Parameters: 2070 another GSSName object to compare with. 2072 7.2.4 equals 2074 public boolean equals(Object another) 2075 A variation of the equals method described in 7.2.3 that is provided 2076 to override the Object.equals() method that the implementing class 2077 will inherit. The behavior is exactly the same as that in 7.2.3 2078 except that no GSSException is thrown; instead, false will be 2079 returned in the situation where an error occurs. (Note that the Java 2080 language specification requires that two objects that are equal 2081 according to the equals(Object) method must return the same integer 2082 result when the hashCode() method is called on them.) 2084 Parameters: 2086 another GSSName object to compare with. 2088 7.2.5 canonicalize 2090 public GSSName canonicalize(Oid mech) throws GSSException 2092 Creates a mechanism name (MN) from an arbitrary internal name. This 2093 is equivalent to using the factory methods described in 7.1.8 or 2094 7.1.9 that take the mechanism name as one of their parameters. 2096 Parameters: 2098 mech The oid for the mechanism for which the canonical form 2099 of the name is requested. 2101 7.2.6 export 2103 public byte[] export() throws GSSException 2105 Returns a canonical contiguous byte representation of a mechanism 2106 name (MN), suitable for direct, byte by byte comparison by 2107 authorization functions. If the name is not an MN, implementations 2108 may throw a GSSException with the NAME_NOT_MN status code. If an 2109 implementation chooses not to throw an exception, it should use some 2110 system specific default mechanism to canonicalize the name and then 2111 export it. The format of the header of the output buffer is 2112 specified in RFC 2743. 2114 7.2.7 toString 2116 public String toString() 2118 Returns a textual representation of the GSSName object. To retrieve 2119 the printed name format, which determines the syntax of the returned 2120 string, the getStringNameType method can be used. 2122 7.2.8 getStringNameType 2124 public Oid getStringNameType() throws GSSException 2126 Returns the oid representing the type of name returned through the 2127 toString method. Using this oid, the syntax of the printable name 2128 can be determined. 2130 7.2.9 isAnonymous 2132 public boolean isAnonymous() 2134 Tests if this name object represents an anonymous entity. Returns 2135 "true" if this is an anonymous name. 2137 7.2.10 isMN 2139 public boolean isMN() 2141 Tests if this name object contains only one mechanism element and is 2142 thus a mechanism name as defined by RFC 2743. 2144 7.3 public interface GSSCredential implements Cloneable 2146 This interface encapsulates the GSS-API credentials for an entity. A 2147 credential contains all the necessary cryptographic information to 2148 enable the creation of a context on behalf of the entity that it 2149 represents. It may contain multiple, distinct, mechanism specific 2150 credential elements, each containing information for a specific 2151 security mechanism, but all referring to the same entity. 2153 A credential may be used to perform context initiation, acceptance, 2154 or both. 2156 GSS-API implementations must impose a local access-control policy on 2157 callers to prevent unauthorized callers from acquiring credentials to 2158 which they are not entitled. GSS-API credential creation is not 2159 intended to provide a "login to the network" function, as such a 2160 function would involve the creation of new credentials rather than 2161 merely acquiring a handle to existing credentials. Such functions, 2162 if required, should be defined in implementation-specific extensions 2163 to the API. 2165 If credential acquisition is time-consuming for a mechanism, the 2166 mechanism may choose to delay the actual acquisition until the 2167 credential is required (e.g. by GSSContext). Such mechanism- 2168 specific implementation decisions should be invisible to the calling 2169 application; thus the query methods immediately following the 2170 creation of a credential object must return valid credential data, 2171 and may therefore incur the overhead of a deferred credential 2172 acquisition. 2174 Applications will create a credential object passing the desired 2175 parameters. The application can then use the query methods to obtain 2176 specific information about the instantiated credential object 2177 (equivalent to the gss_inquire routines). When the credential is no 2178 longer needed, the application should call the dispose (equivalent to 2179 gss_release_cred) method to release any resources held by the 2180 credential object and to destroy any cryptographically sensitive 2181 information. 2183 Classes implementing this interface also implement the Cloneable 2184 interface. This indicates the the class will support the clone() 2185 method that will allow the creation of duplicate credentials. This 2186 is useful when called just before the add() call to retain a copy of 2187 the original credential. 2189 7.3.1 Example Code 2191 This example code demonstrates the creation of a GSSCredential 2192 implementation for a specific entity, querying of its fields, and its 2193 release when it is no longer needed. 2195 GSSManager mgr = GSSManager.getInstance(); 2197 // start by creating a name object for the entity 2198 GSSName name = mgr.createName("userName", GSSName.NT_USER_NAME); 2200 // now acquire credentials for the entity 2201 GSSCredential cred = mgr.createCredential(name, 2202 GSSCredential.ACCEPT_ONLY); 2204 // display credential information - name, remaining lifetime, 2205 // and the mechanisms it has been acquired over 2206 print(cred.getName().toString()); 2207 print(cred.getRemainingLifetime()); 2209 Oid[] mechs = cred.getMechs(); 2210 if (mechs != null) { 2211 for (int i = 0; i < mechs.length; i++) 2212 print(mechs[i].toString()); 2213 } 2215 // release system resources held by the credential 2216 cred.dispose(); 2218 7.3.2 Static Constants 2220 public static final int INITIATE_AND_ACCEPT 2222 Credential usage flag requesting that it be able to be used for both 2223 context initiation and acceptance. The value of this constant is 0. 2225 public static final int INITIATE_ONLY 2227 Credential usage flag requesting that it be able to be used for 2228 context initiation only. The value of this constant is 1. 2230 public static final int ACCEPT_ONLY 2232 Credential usage flag requesting that it be able to be used for 2233 context acceptance only. The value of this constant is 2. 2235 public static final int DEFAULT_LIFETIME 2237 A lifetime constant representing the default credential lifetime. 2238 The value of this constant is 0. 2240 public static final int INDEFINITE_LIFETIME 2242 A lifetime constant representing indefinite credential lifetime. The 2243 value of this constant is the maximum integer value in Java - 2244 Integer.MAX_VALUE. 2246 7.3.3 dispose 2248 public void dispose() throws GSSException 2250 Releases any sensitive information that the GSSCredential object may 2251 be containing. Applications should call this method as soon as the 2252 credential is no longer needed to minimize the time any sensitive 2253 information is maintained. 2255 7.3.4 getName 2257 public GSSName getName() throws GSSException 2259 Retrieves the name of the entity that the credential asserts. 2261 7.3.5 getName 2263 public GSSName getName(Oid mechOID) throws GSSException 2265 Retrieves a mechanism name of the entity that the credential asserts. 2267 Equivalent to calling canonicalize() on the name returned by 7.3.4. 2269 Parameters: 2271 mechOID The mechanism for which information should be returned. 2273 7.3.6 getRemainingLifetime 2275 public int getRemainingLifetime() throws GSSException 2277 Returns the remaining lifetime in seconds for a credential. The 2278 remaining lifetime is the minimum lifetime for any of the underlying 2279 credential mechanisms. A return value of 2280 GSSCredential.INDEFINITE_LIFETIME indicates that the credential does 2281 not expire. A return value of 0 indicates that the credential is 2282 already expired. 2284 7.3.7 getRemainingInitLifetime 2286 public int getRemainingInitLifetime(Oid mech) throws GSSException 2288 Returns the remaining lifetime is seconds for the credential to 2289 remain capable of initiating security contexts under the specified 2290 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2291 indicates that the credential does not expire for context initiation. 2292 A return value of 0 indicates that the credential is already expired. 2294 Parameters: 2296 mechOID The mechanism for which information should be returned. 2298 7.3.8 getRemainingAcceptLifetime 2300 public int getRemainingAcceptLifetime(Oid mech) throws GSSException 2302 Returns the remaining lifetime is seconds for the credential to 2303 remain capable of accepting security contexts under the specified 2304 mechanism. A return value of GSSCredential.INDEFINITE_LIFETIME 2305 indicates that the credential does not expire for context acceptance. 2306 A return value of 0 indicates that the credential is already expired. 2308 Parameters: 2310 mechOID The mechanism for which information should be returned. 2312 7.3.9 getUsage 2314 public int getUsage() throws GSSException 2316 Returns the credential usage flag as a union over all mechanisms. 2317 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2318 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2320 7.3.10 getUsage 2322 public int getUsage(Oid mechOID) throws GSSException 2324 Returns the credential usage flag for the specified mechanism only. 2325 The return value will be one of GSSCredential.INITIATE_AND_ACCEPT(0), 2326 GSSCredential.INITIATE_ONLY(1), or GSSCredential.ACCEPT_ONLY(2). 2328 Parameters: 2330 mechOID The mechanism for which information should be returned. 2332 7.3.11 getMechs 2334 public Oid[] getMechs() throws GSSException 2336 Returns an array of mechanisms supported by this credential. 2338 7.3.12 add 2340 public void add(GSSName aName, int initLifetime, int acceptLifetime, 2341 Oid mech, int usage) throws GSSException 2343 Adds a mechanism specific credential-element to an existing 2344 credential. This method allows the construction of credentials one 2345 mechanism at a time. 2347 This routine is envisioned to be used mainly by context acceptors 2348 during the creation of acceptance credentials which are to be used 2349 with a variety of clients using different security mechanisms. 2351 This routine adds the new credential element "in-place". To add the 2352 element in a new credential, first call clone() to obtain a copy of 2353 this credential, then call its add() method. 2355 Parameters: 2357 aName Name of the principal for whom this credential is to be 2358 acquired. Use "null" to specify the default principal. 2360 initLifetime The number of seconds that credentials should remain 2361 valid for initiating of security contexts. Use 2362 GSSCredential.INDEFINITE_LIFETIME to request that the credentials 2363 have the maximum permitted lifetime. Use 2364 GSSCredential.DEFAULT_LIFETIME to request default credential 2365 lifetime. 2367 acceptLifetime The number of seconds that credentials should 2368 remain valid for accepting of security contexts. Use 2369 GSSCredential.INDEFINITE_LIFETIME to request that the credentials 2370 have the maximum permitted lifetime. Use 2371 GSSCredential.DEFAULT_LIFETIME to request default credential 2372 lifetime. 2374 mech The mechanisms over which the credential is to be 2375 acquired. 2377 usage The intended usage for this credential object. The 2378 value of this parameter must be one of: 2379 GSSCredential.INITIATE_AND_ACCEPT(0), 2380 GSSCredential.INITIATE_ONLY(1), GSSCredential.ACCEPT_ONLY(2) 2382 7.3.13 equals 2384 public boolean equals(Object another) 2386 Tests if this GSSCredential refers to the same entity as the supplied 2387 object. The two credentials must be acquired over the same 2388 mechanisms and must refer to the same principal. Returns "true" if 2389 the two GSSCredentials refer to the same entity; "false" otherwise. 2390 (Note that the Java language specification [JLS] requires that two 2391 objects that are equal according to the equals(Object) method must 2392 return the same integer result when the hashCode() method is called 2393 on them.) 2395 Parameters: 2397 another Another GSSCredential object for comparison. 2399 7.4 public interface GSSContext 2401 This interface encapsulates the GSS-API security context and provides 2402 the security services (wrap, unwrap, getMIC, verifyMIC) that are 2403 available over the context. Security contexts are established 2404 between peers using locally acquired credentials. Multiple contexts 2405 may exist simultaneously between a pair of peers, using the same or 2406 different set of credentials. GSS-API functions in a manner 2407 independent of the underlying transport protocol and depends on its 2408 calling application to transport its tokens between peers. 2410 Before the context establishment phase is initiated, the context 2411 initiator may request specific characteristics desired of the 2412 established context. These can be set using the set methods. After 2413 the context is established, the caller can check the actual 2414 characteristic and services offered by the context using the query 2415 methods. 2417 The context establishment phase begins with the first call to the 2418 init method by the context initiator. During this phase the 2419 initSecContext and acceptSecContext methods will produce GSS-API 2420 authentication tokens which the calling application needs to send to 2421 its peer. If an error occurs at any point, an exception will get 2422 thrown and the code will start executing in a catch block. If not, 2423 the normal flow of code continues and the application can make a call 2424 to the isEstablished() method. If this method returns false it 2425 indicates that a token is needed from its peer in order to continue 2426 the context establishment phase. A return value of true signals that 2427 the local end of the context is established. This may still require 2428 that a token be sent to the peer, if one is produced by GSS-API. 2429 During the context establishment phase, the isProtReady() method may 2430 be called to determine if the context can be used for the per-message 2431 operations. This allows applications to use per-message operations 2432 on contexts which aren't fully established. 2434 After the context has been established or the isProtReady() method 2435 returns "true", the query routines can be invoked to determine the 2436 actual characteristics and services of the established context. The 2437 application can also start using the per-message methods of wrap and 2438 getMIC to obtain cryptographic operations on application supplied 2439 data. 2441 When the context is no longer needed, the application should call 2442 dispose to release any system resources the context may be using. 2444 7.4.1 Example Code 2446 The example code presented below demonstrates the usage of the 2447 GSSContext interface for the initiating peer. Different operations 2448 on the GSSContext object are presented, including: object 2449 instantiation, setting of desired flags, context establishment, query 2450 of actual context flags, per-message operations on application data, 2451 and finally context deletion. 2453 GSSManager mgr = GSSManager.getInstance(); 2454 // start by creating the name for a service entity 2455 GSSName targetName = mgr.createName("service@host", 2456 GSSName.NT_HOSTBASED_SERVICE); 2458 // create a context using default credentials for the above entity 2459 // and the implementation specific default mechanism 2460 GSSContext context = mgr.createContext(targetName, 2461 null, /* default mechanism */ 2462 null, /* default credentials */ 2463 GSSContext.INDEFINITE_LIFETIME); 2465 // set desired context options - all others are false by default 2466 context.requestConf(true); 2467 context.requestMutualAuth(true); 2468 context.requestReplayDet(true); 2469 context.requestSequenceDet(true); 2471 // establish a context between peers - using byte arrays 2472 byte[]inTok = new byte[0]; 2474 try { 2475 do { 2476 byte[] outTok = context.initSecContext(inTok, 0, 2477 inTok.length); 2479 // send the token if present 2480 if (outTok != null) 2481 sendToken(outTok); 2483 // check if we should expect more tokens 2484 if (context.isEstablished()) 2485 break; 2487 // another token expected from peer 2488 inTok = readToken(); 2490 } while (true); 2492 } catch (GSSException e) { 2493 print("GSSAPI error: " + e.getMessage()); 2494 } 2496 // display context information 2497 print("Remaining lifetime in seconds = " + context.getLifetime()); 2498 print("Context mechanism = " + context.getMech().toString()); 2499 print("Initiator = " + context.getSrcName().toString()); 2500 print("Acceptor = " + context.getTargName().toString()); 2501 if (context.getConfState()) 2502 print("Confidentiality security service available"); 2504 if (context.getIntegState()) 2505 print("Integrity security service available"); 2507 // perform wrap on an application supplied message, appMsg, 2508 // using QOP = 0, and requesting privacy service 2509 byte[] appMsg ... 2511 MessageProp mProp = new MessageProp(0, true); 2513 byte[] tok = context.wrap(appMsg, 0, appMsg.length, mProp); 2515 if (mProp.getPrivacy()) 2516 print("Message protected with privacy."); 2518 sendToken(tok); 2520 // release the local-end of the context 2521 context.dispose(); 2523 7.4.2 Static Constants 2525 public static final int DEFAULT_LIFETIME 2527 A lifetime constant representing the default context lifetime. The 2528 value of this constant is 0. 2530 public static final int INDEFINITE_LIFETIME 2532 A lifetime constant representing indefinite context lifetime. The 2533 value of this constant is the maximum integer value in Java - 2534 Integer.MAX_VALUE. 2536 7.4.3 initSecContext 2538 public byte[] initSecContext(byte[] inputBuf, int offset, int len) 2539 throws GSSException 2541 Called by the context initiator to start the context creation 2542 process. This is equivalent to the stream based method except that 2543 the token buffers are handled as byte arrays instead of using stream 2544 objects. This method may return an output token which the 2545 application will need to send to the peer for processing by the 2546 accept call. Typically, the application would do so by calling the 2547 flush() method on an OutputStream that encapsulates the connection 2548 between the two peers. The application can call isEstablished() to 2549 determine if the context establishment phase is complete for this 2550 peer. A return value of "false" from isEstablished() indicates that 2551 more tokens are expected to be supplied to the initSecContext() 2552 method. Note that it is possible that the initSecContext() method 2553 return a token for the peer, and isEstablished() return "true" also. 2554 This indicates that the token needs to be sent to the peer, but the 2555 local end of the context is now fully established. 2557 Upon completion of the context establishment, the available context 2558 options may be queried through the get methods. 2560 Parameters: 2562 inputBuf Token generated by the peer. This parameter is ignored 2563 on the first call. 2565 offset The offset within the inputBuf where the token begins. 2567 len The length of the token within the inputBuf (starting at 2568 the offset). 2570 7.4.4 Example Code 2572 // Create a new GSSContext implementation object. 2573 // GSSContext wrapper implements interface GSSContext. 2574 GSSContext context = mgr.createContext(...); 2576 byte[] inTok = new byte[0]; 2578 try { 2579 do { 2580 byte[] outTok = context.initSecContext(inTok, 0, 2581 inTok.length); 2583 // send the token if present 2584 if (outTok != null) 2585 sendToken(outTok); 2587 // check if we should expect more tokens 2588 if (context.isEstablished()) 2589 break; 2591 // another token expected from peer 2592 inTok = readToken(); 2593 } while (true); 2595 } catch (GSSException e) { 2596 print("GSSAPI error: " + e.getMessage()); 2597 } 2599 7.4.5 initSecContext 2601 public int initSecContext(InputStream inStream, 2602 OutputStream outStream) throws GSSException 2604 Called by the context initiator to start the context creation 2605 process. This is equivalent to the byte array based method. This 2606 method may write an output token to the outStream, which the 2607 application will need to send to the peer for processing by the 2608 accept call. Typically, the application would do so by calling the 2609 flush() method on an OutputStream that encapsulates the connection 2610 between the two peers. The application can call isEstablished() to 2611 determine if the context establishment phase is complete for this 2612 peer. A return value of "false" from isEstablished indicates that 2613 more tokens are expected to be supplied to the initSecContext method. 2614 Note that it is possible that the initSecContext() method return a 2615 token for the peer, and isEstablished() return "true" also. This 2616 indicates that the token needs to be sent to the peer, but the local 2617 end of the context is now fully established. 2619 The GSS-API authentication tokens contain a definitive start and end. 2620 This method will attempt to read one of these tokens per invocation, 2621 and may block on the stream if only part of the token is available. 2623 Upon completion of the context establishment, the available context 2624 options may be queried through the get methods. 2626 Parameters: 2628 inStream Contains the token generated by the peer. This 2629 parameter is ignored on the first call. 2631 outStream Output stream where the output token will be written. 2632 During the final stage of context establishment, there may be no 2633 bytes written. 2635 7.4.6 Example Code 2637 This sample code merely demonstrates the token exchange during the 2638 context establishment phase. It is expected that most Java 2639 applications will use custom implementations of the Input and Output 2640 streams that encapsulate the communication routines. For instance, a 2641 simple read on the application InputStream, when called by the 2642 Context, might cause a token to be read from the peer, and a simple 2643 flush() on the application OutputStream might cause a previously 2644 written token to be transmitted to the peer. 2646 // Create a new GSSContext implementation object. 2647 // GSSContext wrapper implements interface GSSContext. 2648 GSSContext context = mgr.createContext(...); 2650 // use standard java.io stream objects 2651 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2652 ByteArrayInputStream is = null; 2654 try { 2655 do { 2656 context.initSecContext(is, os); 2658 // send token if present 2659 if (os.size() > 0) 2660 sendToken(os); 2662 // check if we should expect more tokens 2663 if (context.isEstablished()) 2664 break; 2666 // another token expected from peer 2667 is = recvToken(); 2669 } while (true); 2671 } catch (GSSException e) { 2672 print("GSSAPI error: " + e.getMessage()); 2673 } 2675 7.4.7 acceptSecContext 2677 public byte[] acceptSecContext(byte[] inTok, int offset, int len) 2678 throws GSSException 2680 Called by the context acceptor upon receiving a token from the peer. 2681 This call is equivalent to the stream based method except that the 2682 token buffers are handled as byte arrays instead of using stream 2683 objects. 2685 This method may return an output token which the application will 2686 need to send to the peer for further processing by the init call. 2688 "null" return value indicates that no token needs to be sent to the 2689 peer. The application can call isEstablished() to determine if the 2690 context establishment phase is complete for this peer. A return 2691 value of "false" from isEstablished() indicates that more tokens are 2692 expected to be supplied to this method. 2694 Note that it is possible that acceptSecContext() return a token for 2695 the peer, and isEstablished() return "true" also. This indicates 2696 that the token needs to be sent to the peer, but the local end of the 2697 context is now fully established. 2699 Upon completion of the context establishment, the available context 2700 options may be queried through the get methods. 2702 Parameters: 2704 inTok Token generated by the peer. 2706 offset The offset within the inTok where the token begins. 2708 len The length of the token within the inTok (starting at 2709 the offset). 2711 7.4.8 Example Code 2713 // acquire server credentials 2714 GSSCredential server = mgr.createCredential(...); 2716 // create acceptor GSS-API context from the default provider 2717 GSSContext context = mgr.createContext(server, null); 2719 try { 2720 do { 2721 byte[] inTok = readToken(); 2723 byte[] outTok = context.acceptSecContext(inTok, 0, 2724 inTok.length); 2726 // possibly send token to peer 2727 if (outTok != null) 2728 sendToken(outTok); 2730 // check if local context establishment is complete 2731 if (context.isEstablished()) 2732 break; 2733 } while (true); 2735 } catch (GSSException e) { 2736 print("GSS-API error: " + e.getMessage()); 2737 } 2739 7.4.9 acceptSecContext 2741 public void acceptSecContext(InputStream inStream, 2742 OutputStream outStream) throws GSSException 2744 Called by the context acceptor upon receiving a token from the peer. 2745 This call is equivalent to the byte array method. It may write an 2746 output token to the outStream, which the application will need to 2747 send to the peer for processing by its initSecContext method. 2748 Typically, the application would do so by calling the flush() method 2749 on an OutputStream that encapsulates the connection between the two 2750 peers. The application can call isEstablished() to determine if the 2751 context establishment phase is complete for this peer. A return 2752 value of "false" from isEstablished() indicates that more tokens are 2753 expected to be supplied to this method. 2755 Note that it is possible that acceptSecContext() return a token for 2756 the peer, and isEstablished() return "true" also. This indicates 2757 that the token needs to be sent to the peer, but the local end of the 2758 context is now fully established. 2760 The GSS-API authentication tokens contain a definitive start and end. 2761 This method will attempt to read one of these tokens per invocation, 2762 and may block on the stream if only part of the token is available. 2764 Upon completion of the context establishment, the available context 2765 options may be queried through the get methods. 2767 Parameters: 2769 inStream Contains the token generated by the peer. 2771 outStream Output stream where the output token will be written. 2772 During the final stage of context establishment, there may be no 2773 bytes written. 2775 7.4.10 Example Code 2777 This sample code merely demonstrates the token exchange during the 2778 context establishment phase. It is expected that most Java 2779 applications will use custom implementations of the Input and Output 2780 streams that encapsulate the communication routines. For instance, a 2781 simple read on the application InputStream, when called by the 2782 Context, might cause a token to be read from the peer, and a simple 2783 flush() on the application OutputStream might cause a previously 2784 written token to be transmitted to the peer. 2786 // acquire server credentials 2787 GSSCredential server = mgr.createCredential(...); 2789 // create acceptor GSS-API context from the default provider 2790 GSSContext context = mgr.createContext(server, null); 2792 // use standard java.io stream objects 2793 ByteArrayOutputStream os = new ByteArrayOutputStream(); 2794 ByteArrayInputStream is = null; 2796 try { 2797 do { 2799 is = recvToken(); 2801 context.acceptSecContext(is, os); 2803 // possibly send token to peer 2804 if (os.size() > 0) 2805 sendToken(os); 2807 // check if local context establishment is complete 2808 if (context.isEstablished()) 2809 break; 2810 } while (true); 2812 } catch (GSSException e) { 2813 print("GSS-API error: " + e.getMessage()); 2814 } 2816 7.4.11 isEstablished 2818 public boolean isEstablished() 2820 Used during context establishment to determine the state of the 2821 context. Returns "true" if this is a fully established context on 2822 the caller's side and no more tokens are needed from the peer. 2823 Should be called after a call to initSecContext() or 2824 acceptSecContext() when no GSSException is thrown. 2826 7.4.12 dispose 2828 public void dispose() throws GSSException 2830 Releases any system resources and cryptographic information stored in 2831 the context object. This will invalidate the context. 2833 7.4.13 getWrapSizeLimit 2835 public int getWrapSizeLimit(int qop, boolean confReq, 2836 int maxTokenSize) throws GSSException 2838 Returns the maximum message size that, if presented to the wrap 2839 method with the same confReq and qop parameters, will result in an 2840 output token containing no more than the maxTokenSize bytes. 2842 This call is intended for use by applications that communicate over 2843 protocols that impose a maximum message size. It enables the 2844 application to fragment messages prior to applying protection. 2846 GSS-API implementations are recommended but not required to detect 2847 invalid QOP values when getWrapSizeLimit is called. This routine 2848 guarantees only a maximum message size, not the availability of 2849 specific QOP values for message protection. 2851 Successful completion of this call does not guarantee that wrap will 2852 be able to protect a message of the computed length, since this 2853 ability may depend on the availability of system resources at the 2854 time that wrap is called. However, if the implementation itself 2855 imposes an upper limit on the length of messages that may be 2856 processed by wrap, the implementation should not return a value that 2857 is greater than this length. 2859 Parameters: 2861 qop Indicates the level of protection wrap will be asked to 2862 provide. 2864 confReq Indicates if wrap will be asked to provide privacy 2865 service. 2867 maxTokenSize The desired maximum size of the token emitted by 2868 wrap. 2870 7.4.14 wrap 2872 public byte[] wrap(byte[] inBuf, int offset, int len, 2873 MessageProp msgProp) throws GSSException 2875 Applies per-message security services over the established security 2876 context. The method will return a token with a cryptographic MIC and 2877 may optionally encrypt the specified inBuf. This method is 2878 equivalent in functionality to its stream counterpart. The returned 2879 byte array will contain both the MIC and the message. 2881 The MessageProp object is instantiated by the application and used to 2882 specify a QOP value which selects cryptographic algorithms, and a 2883 privacy service to optionally encrypt the message. The underlying 2884 mechanism that is used in the call may not be able to provide the 2885 privacy service. It sets the actual privacy service that it does 2886 provide in this MessageProp object which the caller should then query 2887 upon return. If the mechanism is not able to provide the requested 2888 QOP, it throws a GSSException with the BAD_QOP code. 2890 Since some application-level protocols may wish to use tokens emitted 2891 by wrap to provide "secure framing", implementations should support 2892 the wrapping of zero-length messages. 2894 The application will be responsible for sending the token to the 2895 peer. 2897 Parameters: 2899 inBuf Application data to be protected. 2901 offset The offset within the inBuf where the data begins. 2903 len The length of the data within the inBuf (starting at the 2904 offset). 2906 msgProp Instance of MessageProp that is used by the application 2907 to set the desired QOP and privacy state. Set the desired QOP to 2908 0 to request the default QOP. Upon return from this method, this 2909 object will contain the the actual privacy state that was applied 2910 to the message by the underlying mechanism. 2912 7.4.15 wrap 2914 public void wrap(InputStream inStream, OutputStream outStream, 2915 MessageProp msgProp) throws GSSException 2917 Allows to apply per-message security services over the established 2918 security context. The method will produce a token with a 2919 cryptographic MIC and may optionally encrypt the message in inStream. 2920 The outStream will contain both the MIC and the message. 2922 The MessageProp object is instantiated by the application and used to 2923 specify a QOP value which selects cryptographic algorithms, and a 2924 privacy service to optionally encrypt the message. The underlying 2925 mechanism that is used in the call may not be able to provide the 2926 privacy service. It sets the actual privacy service that it does 2927 provide in this MessageProp object which the caller should then query 2928 upon return. If the mechanism is not able to provide the requested 2929 QOP, it throws a GSSException with the BAD_QOP code. 2931 Since some application-level protocols may wish to use tokens emitted 2932 by wrap to provide "secure framing", implementations should support 2933 the wrapping of zero-length messages. 2935 The application will be responsible for sending the token to the 2936 peer. 2938 Parameters: 2940 inStream Input stream containing the application data to be 2941 protected. 2943 outStream The output stream to write the protected message to. 2944 The application is responsible for sending this to the other peer 2945 for processing in its unwrap method. 2947 msgProp Instance of MessageProp that is used by the application 2948 to set the desired QOP and privacy state. Set the desired QOP to 2949 0 to request the default QOP. Upon return from this method, this 2950 object will contain the the actual privacy state that was applied 2951 to the message by the underlying mechanism. 2953 7.4.16 unwrap 2955 public byte[] unwrap(byte[] inBuf, int offset, int len, 2956 MessageProp msgProp) throws GSSException 2958 Used by the peer application to process tokens generated with the 2959 wrap call. This call is equal in functionality to its stream 2960 counterpart. The method will return the message supplied in the peer 2961 application to the wrap call, verifying the embedded MIC. 2963 The MessageProp object is instantiated by the application and is used 2964 by the underlying mechanism to return information to the caller such 2965 as the QOP, whether confidentiality was applied to the message, and 2966 other supplementary message state information. 2968 Since some application-level protocols may wish to use tokens emitted 2969 by wrap to provide "secure framing", implementations should support 2970 the wrapping and unwrapping of zero-length messages. 2972 Parameters: 2974 inBuf GSS-API wrap token received from peer. 2976 offset The offset within the inBuf where the token begins. 2978 len The length of the token within the inBuf (starting at 2979 the offset). 2981 msgProp Upon return from the method, this object will contain 2982 the applied QOP, the privacy state of the message, and 2983 supplementary information described in 5.12.3 stating whether the 2984 token was a duplicate, old, out of sequence or arriving after a 2985 gap. 2987 7.4.17 unwrap 2989 public void unwrap(InputStream inStream, OutputStream outStream, 2990 MessageProp msgProp) throws GSSException 2992 Used by the peer application to process tokens generated with the 2993 wrap call. This call is equal in functionality to its byte array 2994 counterpart. It will produce the message supplied in the peer 2995 application to the wrap call, verifying the embedded MIC. 2997 The MessageProp object is instantiated by the application and is used 2998 by the underlying mechanism to return information to the caller such 2999 as the QOP, whether confidentiality was applied to the message, and 3000 other supplementary message state information. 3002 Since some application-level protocols may wish to use tokens emitted 3003 by wrap to provide "secure framing", implementations should support 3004 the wrapping and unwrapping of zero-length messages. 3006 Parameters: 3008 inStream Input stream containing the GSS-API wrap token received 3009 from the peer. 3011 outStream The output stream to write the application message to. 3013 msgProp Upon return from the method, this object will contain 3014 the applied QOP, the privacy state of the message, and 3015 supplementary information described in 5.12.3 stating whether the 3016 token was a duplicate, old, out of sequence or arriving after a 3017 gap. 3019 7.4.18 getMIC 3021 public byte[] getMIC(byte[] inMsg, int offset, int len, 3022 MessageProp msgProp) throws GSSException 3024 Returns a token containing a cryptographic MIC for the supplied 3025 message, for transfer to the peer application. Unlike wrap, which 3026 encapsulates the user message in the returned token, only the message 3027 MIC is returned in the output token. This method is identical in 3028 functionality to its stream counterpart. 3030 Note that privacy can only be applied through the wrap call. 3032 Since some application-level protocols may wish to use tokens emitted 3033 by getMIC to provide "secure framing", implementations should support 3034 derivation of MICs from zero-length messages. 3036 Parameters: 3038 inMsg Message to generate MIC over. 3040 offset The offset within the inMsg where the token begins. 3042 len The length of the token within the inMsg (starting at 3043 the offset). 3045 msgProp Instance of MessageProp that is used by the application 3046 to set the desired QOP. Set the desired QOP to 0 in msgProp to 3047 request the default QOP. Alternatively pass in "null" for msgProp 3048 to request default QOP. 3050 7.4.19 getMIC 3052 public void getMIC(InputStream inStream, OutputStream outStream, 3053 MessageProp msgProp) throws GSSException 3055 Produces a token containing a cryptographic MIC for the supplied 3056 message, for transfer to the peer application. Unlike wrap, which 3057 encapsulates the user message in the returned token, only the message 3058 MIC is produced in the output token. This method is identical in 3059 functionality to its byte array counterpart. 3061 Note that privacy can only be applied through the wrap call. 3063 Since some application-level protocols may wish to use tokens emitted 3064 by getMIC to provide "secure framing", implementations should support 3065 derivation of MICs from zero-length messages. 3067 Parameters: 3069 inStream Input stream containing the message to generate MIC 3070 over. 3072 outStream Output stream to write the GSS-API output token to. 3074 msgProp Instance of MessageProp that is used by the application 3075 to set the desired QOP. Set the desired QOP to 0 in msgProp to 3076 request the default QOP. Alternatively pass in "null" for msgProp 3077 to request default QOP. 3079 7.4.20 verifyMIC 3081 public void verifyMIC(byte[] inTok, int tokOffset, int tokLen, 3082 byte[] inMsg, int msgOffset, int msgLen, 3083 MessageProp msgProp) throws GSSException 3085 Verifies the cryptographic MIC, contained in the token parameter, 3086 over the supplied message. This method is equivalent in 3087 functionality to its stream counterpart. 3089 The MessageProp object is instantiated by the application and is used 3090 by the underlying mechanism to return information to the caller such 3091 as the QOP indicating the strength of protection that was applied to 3092 the message and other supplementary message state information. 3094 Since some application-level protocols may wish to use tokens emitted 3095 by getMIC to provide "secure framing", implementations should support 3096 the calculation and verification of MICs over zero-length messages. 3098 Parameters: 3100 inTok Token generated by peer's getMIC method. 3102 tokOffset The offset within the inTok where the token begins. 3104 tokLen The length of the token within the inTok (starting at 3105 the offset). 3107 inMsg Application message to verify the cryptographic MIC 3108 over. 3110 msgOffset The offset within the inMsg where the message begins. 3112 msgLen The length of the message within the inMsg (starting at 3113 the offset). 3115 msgProp Upon return from the method, this object will contain 3116 the applied QOP and supplementary information described in 5.12.3 3117 stating whether the token was a duplicate, old, out of sequence or 3118 arriving after a gap. The confidentiality state will be set to 3119 "false". 3121 7.4.21 verifyMIC 3123 public void verifyMIC(InputStream tokStream, InputStream msgStream, 3124 MessageProp msgProp) throws GSSException 3126 Verifies the cryptographic MIC, contained in the token parameter, 3127 over the supplied message. This method is equivalent in 3128 functionality to its byte array counterpart. 3130 The MessageProp object is instantiated by the application and is used 3131 by the underlying mechanism to return information to the caller such 3132 as the QOP indicating the strength of protection that was applied to 3133 the message and other supplementary message state information. 3135 Since some application-level protocols may wish to use tokens emitted 3136 by getMIC to provide "secure framing", implementations should support 3137 the calculation and verification of MICs over zero-length messages. 3139 Parameters: 3141 tokStream Input stream containing the token generated by peer's 3142 getMIC method. 3144 msgStream Input stream containing the application message to 3145 verify the cryptographic MIC over. 3147 msgProp Upon return from the method, this object will contain 3148 the applied QOP and supplementary information described in 5.12.3 3149 stating whether the token was a duplicate, old, out of sequence or 3150 arriving after a gap. The confidentiality state will be set to 3151 "false". 3153 7.4.22 export 3155 public byte[] export() throws GSSException 3157 Provided to support the sharing of work between multiple processes. 3158 This routine will typically be used by the context-acceptor, in an 3159 application where a single process receives incoming connection 3160 requests and accepts security contexts over them, then passes the 3161 established context to one or more other processes for message 3162 exchange. 3164 This method deactivates the security context and creates an 3165 interprocess token which, when passed to the byte array constructor 3166 of the GSSContext interface in another process, will re-activate the 3167 context in the second process. Only a single instantiation of a 3168 given context may be active at any one time; a subsequent attempt by 3169 a context exporter to access the exported security context will fail. 3171 The implementation may constrain the set of processes by which the 3172 interprocess token may be imported, either as a function of local 3173 security policy, or as a result of implementation decisions. For 3174 example, some implementations may constrain contexts to be passed 3175 only between processes that run under the same account, or which are 3176 part of the same process group. 3178 The interprocess token may contain security-sensitive information 3179 (for example cryptographic keys). While mechanisms are encouraged to 3180 either avoid placing such sensitive information within interprocess 3181 tokens, or to encrypt the token before returning it to the 3182 application, in a typical GSS-API implementation this may not be 3183 possible. Thus the application must take care to protect the 3184 interprocess token, and ensure that any process to which the token is 3185 transferred is trustworthy. 3187 7.4.23 requestMutualAuth 3189 public void requestMutualAuth(boolean state) throws GSSException 3191 Sets the request state of the mutual authentication flag for the 3192 context. This method is only valid before the context creation 3193 process begins and only for the initiator. 3195 Parameters: 3197 state Boolean representing if mutual authentication should be 3198 requested during context establishment. 3200 7.4.24 requestReplayDet 3202 public void requestReplayDet(boolean state) throws GSSException 3204 Sets the request state of the replay detection service for the 3205 context. This method is only valid before the context creation 3206 process begins and only for the initiator. 3208 Parameters: 3210 state Boolean representing if replay detection is desired over 3211 the established context. 3213 7.4.25 requestSequenceDet 3215 public void requestSequenceDet(boolean state) throws GSSException 3217 Sets the request state for the sequence checking service of the 3218 context. This method is only valid before the context creation 3219 process begins and only for the initiator. 3221 Parameters: 3223 state Boolean representing if sequence detection is desired 3224 over the established context. 3226 7.4.26 requestCredDeleg 3228 public void requestCredDeleg(boolean state) throws GSSException 3230 Sets the request state for the credential delegation flag for the 3231 context. This method is only valid before the context creation 3232 process begins and only for the initiator. 3234 Parameters: 3236 state Boolean representing if credential delegation is 3237 desired. 3239 7.4.27 requestAnonymity 3241 public void requestAnonymity(boolean state) throws GSSException 3243 Requests anonymous support over the context. This method is only 3244 valid before the context creation process begins and only for the 3245 initiator. 3247 Parameters: 3249 state Boolean representing if anonymity support is requested. 3251 7.4.28 requestConf 3253 public void requestConf(boolean state) throws GSSException 3255 Requests that confidentiality service be available over the context. 3256 This method is only valid before the context creation process begins 3257 and only for the initiator. 3259 Parameters: 3261 state Boolean indicating if confidentiality services are to be 3262 requested for the context. 3264 7.4.29 requestInteg 3266 public void requestInteg(boolean state) throws GSSException 3268 Requests that integrity services be available over the context. This 3269 method is only valid before the context creation process begins and 3270 only for the initiator. 3272 Parameters: 3274 state Boolean indicating if integrity services are to be 3275 requested for the context. 3277 7.4.30 requestLifetime 3279 public void requestLifetime(int lifetime) throws GSSException 3281 Sets the desired lifetime for the context in seconds. This method is 3282 only valid before the context creation process begins and only for 3283 the initiator. Use GSSContext.INDEFINITE_LIFETIME and 3284 GSSContext.DEFAULT_LIFETIME to request indefinite or default context 3285 lifetime. 3287 Parameters: 3289 lifetime The desired context lifetime in seconds. 3291 7.4.31 setChannelBinding 3293 public void setChannelBinding(ChannelBinding cb) throws GSSException 3295 Sets the channel bindings to be used during context establishment. 3297 This method is only valid before the context creation process begins. 3299 Parameters: 3301 cb Channel bindings to be used. 3303 7.4.32 getCredDelegState 3305 public boolean getCredDelegState() 3307 Returns the state of the delegated credentials for the context. When 3308 issued before context establishment is completed or when the 3309 isProtReady method returns "false", it returns the desired state, 3310 otherwise it will indicate the actual state over the established 3311 context. 3313 7.4.33 getMutualAuthState 3315 public boolean getMutualAuthState() 3317 Returns the state of the mutual authentication option for the 3318 context. When issued before context establishment completes or when 3319 the isProtReady method returns "false", it returns the desired state, 3320 otherwise it will indicate the actual state over the established 3321 context. 3323 7.4.34 getReplayDetState 3325 public boolean getReplayDetState() 3327 Returns the state of the replay detection option for the context. 3328 When issued before context establishment completes or when the 3329 isProtReady method returns "false", it returns the desired state, 3330 otherwise it will indicate the actual state over the established 3331 context. 3333 7.4.35 getSequenceDetState 3335 public boolean getSequenceDetState() 3337 Returns the state of the sequence detection option for the context. 3338 When issued before context establishment completes or when the 3339 isProtReady method returns "false", it returns the desired state, 3340 otherwise it will indicate the actual state over the established 3341 context. 3343 7.4.36 getAnonymityState 3345 public boolean getAnonymityState() 3347 Returns "true" if this is an anonymous context. When issued before 3348 context establishment completes or when the isProtReady method 3349 returns "false", it returns the desired state, otherwise it will 3350 indicate the actual state over the established context. 3352 7.4.37 isTransferable 3354 public boolean isTransferable() throws GSSException 3356 Returns "true" if the context is transferable to other processes 3357 through the use of the export method. This call is only valid on 3358 fully established contexts. 3360 7.4.38 isProtReady 3362 public boolean isProtReady() 3364 Returns "true" if the per message operations can be applied over the 3365 context. Some mechanisms may allow the usage of per-message 3366 operations before the context is fully established. This will also 3367 indicate that the get methods will return actual context state 3368 characteristics instead of the desired ones. 3370 7.4.39 getConfState 3372 public boolean getConfState() 3374 Returns the confidentiality service state over the context. When 3375 issued before context establishment completes or when the isProtReady 3376 method returns "false", it returns the desired state, otherwise it 3377 will indicate the actual state over the established context. 3379 7.4.40 getIntegState 3381 public boolean getIntegState() 3383 Returns the integrity service state over the context. When issued 3384 before context establishment completes or when the isProtReady method 3385 returns "false", it returns the desired state, otherwise it will 3386 indicate the actual state over the established context. 3388 7.4.41 getLifetime 3390 public int getLifetime() 3391 Returns the context lifetime in seconds. When issued before context 3392 establishment completes or when the isProtReady method returns 3393 "false", it returns the desired lifetime, otherwise it will indicate 3394 the remaining lifetime for the context. 3396 7.4.42 getSrcName 3398 public GSSName getSrcName() throws GSSException 3400 Returns the name of the context initiator. This call is valid only 3401 after the context is fully established or the isProtReady method 3402 returns "true". It is guaranteed to return an MN. 3404 7.4.43 getTargName 3406 public GSSName getTargName() throws GSSException 3408 Returns the name of the context target (acceptor). This call is 3409 valid only after the context is fully established or the isProtReady 3410 method returns "true". It is guaranteed to return an MN. 3412 7.4.44 getMech 3414 public Oid getMech() throws GSSException 3416 Returns the mechanism oid for this context. This method may be 3417 called before the context is fully established, but the mechanism 3418 returned may change on successive calls in negotiated mechanism case. 3420 7.4.45 getDelegCred 3422 public GSSCredential getDelegCred() throws GSSException 3424 Returns the delegated credential object on the acceptor's side. To 3425 check for availability of delegated credentials call 3426 getDelegCredState. This call is only valid on fully established 3427 contexts. 3429 7.4.46 isInitiator 3431 public boolean isInitiator() throws GSSException 3433 Returns "true" if this is the initiator of the context. This call is 3434 only valid after the context creation process has started. 3436 7.5 public class MessageProp 3438 This is a utility class used within the per-message GSSContext 3439 methods to convey per-message properties. 3441 When used with the GSSContext interface's wrap and getMIC methods, an 3442 instance of this class is used to indicate the desired QOP and to 3443 request if confidentiality services are to be applied to caller 3444 supplied data (wrap only). To request default QOP, the value of 0 3445 should be used for QOP. 3447 When used with the unwrap and verifyMIC methods of the GSSContext 3448 interface, an instance of this class will be used to indicate the 3449 applied QOP and confidentiality services over the supplied message. 3450 In the case of verifyMIC, the confidentiality state will always be 3451 "false". Upon return from these methods, this object will also 3452 contain any supplementary status values applicable to the processed 3453 token. The supplementary status values can indicate old tokens, out 3454 of sequence tokens, gap tokens or duplicate tokens. 3456 7.5.1 Constructors 3458 public MessageProp(boolean privState) 3460 Constructor which sets QOP to 0 indicating that the default QOP is 3461 requested. 3463 Parameters: 3465 privState The desired privacy state. "true" for privacy and 3466 "false" for integrity only. 3468 public MessageProp(int qop, boolean privState) 3470 Constructor which sets the values for the qop and privacy state. 3472 Parameters: 3474 qop The desired QOP. Use 0 to request a default QOP. 3476 privState The desired privacy state. "true" for privacy and 3477 "false" for integrity only. 3479 7.5.2 getQOP 3481 public int getQOP() 3483 Retrieves the QOP value. 3485 7.5.3 getPrivacy 3487 public boolean getPrivacy() 3489 Retrieves the privacy state. 3491 7.5.4 getMinorStatus 3493 public int getMinorStatus() 3495 Retrieves the minor status that the underlying mechanism might have 3496 set. 3498 7.5.5 getMinorString 3500 public String getMinorString() 3502 Returns a string explaining the mechanism specific error code. null 3503 will be returned when no mechanism error code has been set. 3505 7.5.6 setQOP 3507 public void setQOP(int qopVal) 3509 Sets the QOP value. 3511 Parameters: 3513 qopVal The QOP value to be set. Use 0 to request a default QOP 3514 value. 3516 7.5.7 setPrivacy 3518 public void setPrivacy(boolean privState) 3520 Sets the privacy state. 3522 Parameters: 3524 privState The privacy state to set. 3526 7.5.8 isDuplicateToken 3528 public boolean isDuplicateToken() 3530 Returns "true" if this is a duplicate of an earlier token. 3532 7.5.9 isOldToken 3534 public boolean isOldToken() 3536 Returns "true" if the token's validity period has expired. 3538 7.5.10 isUnseqToken 3540 public boolean isUnseqToken() 3542 Returns "true" if a later token has already been processed. 3544 7.5.11 isGapToken 3546 public boolean isGapToken() 3548 Returns "true" if an expected per-message token was not received. 3550 7.5.12 setSupplementaryStates 3552 public void setSupplementaryStates(boolean duplicate, 3553 boolean old, boolean unseq, boolean gap, 3554 int minorStatus, String minorString) 3556 This method sets the state for the supplementary information flags 3557 and the minor status in MessageProp. It is not used by the 3558 application but by the GSS implementation to return this information 3559 to the caller of a per-message context method. 3561 Parameters: 3563 duplicate true if the token was a duplicate of an earlier token, 3564 false otherwise 3566 old true if the token's validity period has expired, false 3567 otherwise 3569 unseq true if a later token has already been processed, false 3570 otherwise 3572 gap true if one or more predecessor tokens have not yet been 3573 successfully processed, false otherwise 3575 minorStatus the integer minor status code that the underlying 3576 mechanism wants to set 3578 minorString the textual representation of the minorStatus value 3580 7.6 public class ChannelBinding 3582 The GSS-API accommodates the concept of caller-provided channel 3583 binding information. Channel bindings are used to strengthen the 3584 quality with which peer entity authentication is provided during 3585 context establishment. They enable the GSS-API callers to bind the 3586 establishment of the security context to relevant characteristics 3587 like addresses or to application specific data. 3589 The caller initiating the security context must determine the 3590 appropriate channel binding values to set in the GSSContext object. 3591 The acceptor must provide an identical binding in order to validate 3592 that received tokens possess correct channel-related characteristics. 3594 Use of channel bindings is optional in GSS-API. Since channel- 3595 binding information may be transmitted in context establishment 3596 tokens, applications should therefore not use confidential data as 3597 channel-binding components. 3599 7.6.1 Constructors 3601 public ChannelBinding(InetAddress initAddr, InetAddress acceptAddr, 3602 byte[] appData) 3604 Create a ChannelBinding object with user supplied address information 3605 and data. "null" values can be used for any fields which the 3606 application does not want to specify. 3608 Parameters: 3610 initAddr The address of the context initiator. "null" value can 3611 be supplied to indicate that the application does not want to set 3612 this value. 3614 acceptAddr The address of the context acceptor. "null" value can 3615 be supplied to indicate that the application does not want to set 3616 this value. 3618 appData Application supplied data to be used as part of the 3619 channel bindings. "null" value can be supplied to indicate that 3620 the application does not want to set this value. 3622 public ChannelBinding(byte[] appData) 3624 Creates a ChannelBinding object without any addressing information. 3626 Parameters: 3628 appData Application supplied data to be used as part of the 3629 channel bindings. 3631 7.6.2 getInitiatorAddress 3633 public InetAddress getInitiatorAddress() 3635 Returns the initiator's address for this channel binding. "null" is 3636 returned if the address has not been set. 3638 7.6.3 getAcceptorAddress 3640 public InetAddress getAcceptorAddress() 3642 Returns the acceptor's address for this channel binding. "null" is 3643 returned if the address has not been set. 3645 7.6.4 getApplicationData 3647 public byte[] getApplicationData() 3649 Returns application data being used as part of the ChannelBinding. 3650 "null" is returned if no application data has been specified for the 3651 channel binding. 3653 7.6.5 equals 3655 public boolean equals(Object obj) 3657 Returns "true" if two channel bindings match. (Note that the Java 3658 language specification requires that two objects that are equal 3659 according to the equals(Object) method must return the same integer 3660 result when the hashCode() method is called on them.) 3662 Parameters: 3664 obj Another channel binding to compare with. 3666 7.7 public class Oid 3668 This class represents Universal Object Identifiers (Oids) and their 3669 associated operations. 3671 Oids are hierarchically globally-interpretable identifiers used 3672 within the GSS-API framework to identify mechanisms and name formats. 3674 The structure and encoding of Oids is defined in ISOIEC-8824 and 3675 ISOIEC-8825. For example the Oid representation of Kerberos V5 3676 mechanism is "1.2.840.113554.1.2.2" 3678 The GSSName name class contains public static Oid objects 3679 representing the standard name types defined in GSS-API. 3681 7.7.1 Constructors 3683 public Oid(String strOid) throws GSSException 3685 Creates an Oid object from a string representation of its integer 3686 components (e.g. "1.2.840.113554.1.2.2"). 3688 Parameters: 3690 strOid The string representation for the oid. 3692 public Oid(InputStream derOid) throws GSSException 3694 Creates an Oid object from its DER encoding. This refers to the full 3695 encoding including tag and length. The structure and encoding of 3696 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3697 identical in functionality to its byte array counterpart. 3699 Parameters: 3701 derOid Stream containing the DER encoded oid. 3703 public Oid(byte[] DEROid) throws GSSException 3705 Creates an Oid object from its DER encoding. This refers to the full 3706 encoding including tag and length. The structure and encoding of 3707 Oids is defined in ISOIEC-8824 and ISOIEC-8825. This method is 3708 identical in functionality to its byte array counterpart. 3710 Parameters: 3712 derOid Byte array storing a DER encoded oid. 3714 7.7.2 toString 3716 public String toString() 3718 Returns a string representation of the oid's integer components in 3719 dot separated notation (e.g. "1.2.840.113554.1.2.2"). 3721 7.7.3 equals 3723 public boolean equals(Object Obj) 3725 Returns "true" if the two Oid objects represent the same oid value. 3726 (Note that the Java language specification [JLS] requires that two 3727 objects that are equal according to the equals(Object) method must 3728 return the same integer result when the hashCode() method is called 3729 on them.) 3731 Parameters: 3733 obj Another Oid object to compare with. 3735 7.7.4 getDER 3737 public byte[] getDER() 3739 Returns the full ASN.1 DER encoding for this oid object, which 3740 includes the tag and length. 3742 7.7.5 containedIn 3744 public boolean containedIn(Oid[] oids) 3746 A utility method to test if an Oid object is contained within the 3747 supplied Oid object array. 3749 Parameters: 3751 oids An array of oids to search. 3753 7.8 public class GSSException extends Exception 3755 This exception is thrown whenever a fatal GSS-API error occurs 3756 including mechanism specific errors. It may contain both, the major 3757 and minor, GSS-API status codes. The mechanism implementers are 3758 responsible for setting appropriate minor status codes when throwing 3759 this exception. Aside from delivering the numeric error code(s) to 3760 the caller, this class performs the mapping from their numeric values 3761 to textual representations. All Java GSS-API methods are declared 3762 throwing this exception. 3764 All implementations are encouraged to use the Java 3765 internationalization techniques to provide local translations of the 3766 message strings. 3768 7.8.1 Static Constants 3770 All valid major GSS-API error code values are declared as constants 3771 in this class. 3773 public static final int BAD_BINDINGS 3775 Channel bindings mismatch error. The value of this constant is 1. 3777 public static final int BAD_MECH 3779 Unsupported mechanism requested error. The value of this constant is 3780 2 3782 public static final int BAD_NAME 3784 Invalid name provided error. The value of this constant is 3. 3786 public static final int BAD_NAMETYPE 3788 Name of unsupported type provided error. The value of this constant 3789 is 4. 3791 public static final int BAD_STATUS 3793 Invalid status code error - this is the default status value. The 3794 value of this constant is 5. 3796 public static final int BAD_MIC 3798 Token had invalid integrity check error. The value of this constant 3799 is 6. 3801 public static final int CONTEXT_EXPIRED 3803 Specified security context expired error. The value of this constant 3804 is 7. 3806 public static final int CREDENTIALS_EXPIRED 3808 Expired credentials detected error. The value of this constant is 8. 3810 public static final int DEFECTIVE_CREDENTIAL 3812 Defective credential error. The value of this constant is 9. 3814 public static final int DEFECTIVE_TOKEN 3815 Defective token error. The value of this constant is 10. 3817 public static final int FAILURE 3819 General failure, unspecified at GSS-API level. The value of this 3820 constant is 11. 3822 public static final int NO_CONTEXT 3824 Invalid security context error. The value of this constant is 12. 3826 public static final int NO_CRED 3828 Invalid credentials error. The value of this constant is 13. 3830 public static final int BAD_QOP 3832 Unsupported QOP value error. The value of this constant is 14. 3834 public static final int UNAUTHORIZED 3836 Operation unauthorized error. The value of this constant is 15. 3838 public static final int UNAVAILABLE 3840 Operation unavailable error. The value of this constant is 16. 3842 public static final int DUPLICATE_ELEMENT 3844 Duplicate credential element requested error. The value of this 3845 constant is 17. 3847 public static final int NAME_NOT_MN 3849 Name contains multi-mechanism elements error. The value of this 3850 constant is 18. 3852 public static final int DUPLICATE_TOKEN 3854 The token was a duplicate of an earlier token. This is contained in 3855 an exception only when detected during context establishment, in 3856 which case it is considered a fatal error. (Non-fatal supplementary 3857 codes are indicated via the MessageProp object.) The value of this 3858 constant is 19. 3860 public static final int OLD_TOKEN 3862 The token's validity period has expired. This is contained in an 3863 exception only when detected during context establishment, in which 3864 case it is considered a fatal error. (Non-fatal supplementary codes 3865 are indicated via the MessageProp object.) The value of this 3866 constant is 20. 3868 public static final int UNSEQ_TOKEN 3870 A later token has already been processed. This is contained in an 3871 exception only when detected during context establishment, in which 3872 case it is considered a fatal error. (Non-fatal supplementary codes 3873 are indicated via the MessageProp object.) The value of this 3874 constant is 21. 3876 public static final int GAP_TOKEN 3878 An expected per-message token was not received. This is contained in 3879 an exception only when detected during context establishment, in 3880 which case it is considered a fatal error. (Non-fatal supplementary 3881 codes are indicated via the MessageProp object.) The value of this 3882 constant is 22. 3884 7.8.2 Constructors 3886 public GSSException(int majorCode) 3888 Creates a GSSException object with a specified major code. 3890 Parameters: 3892 majorCode The GSS error code causing this exception to be thrown. 3894 public GSSException(int majorCode, int minorCode, String minorString) 3896 Creates a GSSException object with the specified major code, minor 3897 code, and minor code textual explanation. This constructor is to be 3898 used when the exception is originating from the security mechanism. 3899 It allows to specify the GSS code and the mechanism code. 3901 Parameters: 3903 majorCode The GSS error code causing this exception to be thrown. 3905 minorCode The mechanism error code causing this exception to be 3906 thrown. 3908 minorString The textual explanation of the mechanism error code. 3910 7.8.3 getMajor 3912 public int getMajor() 3914 Returns the major code representing the GSS error code that caused 3915 this exception to be thrown. 3917 7.8.4 getMinor 3919 public int getMinor() 3921 Returns the mechanism error code that caused this exception. The 3922 minor code is set by the underlying mechanism. Value of 0 indicates 3923 that mechanism error code is not set. 3925 7.8.5 getMajorString 3927 public String getMajorString() 3929 Returns a string explaining the GSS major error code causing this 3930 exception to be thrown. 3932 7.8.6 getMinorString 3934 public String getMinorString() 3936 Returns a string explaining the mechanism specific error code. null 3937 will be returned when no mechanism error code has been set. 3939 7.8.7 setMinor 3941 public void setMinor(int minorCode, String message) 3943 Used internally by the GSS-API implementation and the underlying 3944 mechanisms to set the minor code and its textual representation. 3946 Parameters: 3948 minorCode The mechanism specific error code. 3950 message A textual explanation of the mechanism error code. 3952 7.8.8 toString 3954 public String toString() 3956 Returns a textual representation of both the major and minor status 3957 codes. 3959 7.8.9 getMessage 3961 public String getMessage() 3963 Returns a detailed message of this exception. Overrides 3964 Throwable.getMessage. It is customary in Java to use this method to 3965 obtain exception information. 3967 8. Sample Applications 3969 8.1 Simple GSS Context Initiator 3971 import org.ietf.jgss.*; 3973 /** 3974 * This is a partial sketch for a simple client program that acts 3975 * as a GSS context initiator. It illustrates how to use the Java 3976 * bindings for the GSS-API specified in 3977 * Generic Security Service API Version 2 : Java bindings 3978 * 3979 * 3980 * This code sketch assumes the existence of a GSS-API 3981 * implementation that supports the mechanism that it will need 3982 * and is present as a library package (org.ietf.jgss) either as 3983 * part of the standard JRE or in the CLASSPATH the application 3984 * specifies. 3985 */ 3987 public class SimpleClient { 3989 private String serviceName; // name of peer (ie. server) 3990 private GSSCredential clientCred = null; 3991 private GSSContext context = null; 3992 private Oid mech; // underlying mechanism to use 3994 private GSSManager mgr = GSSManager.getInstance(); 3996 ... 3997 ... 3999 private void clientActions() { 4000 initializeGSS(); 4001 establishContext(); 4002 doCommunication(); 4003 } 4005 /** 4006 * Acquire credentials for the client. 4007 */ 4008 private void initializeGSS() { 4010 try { 4012 clientCred = mgr.createCredential(null /*default princ*/, 4013 GSSCredential.INDEFINITE_LIFETIME /* max lifetime */, 4014 mech /* mechanism to use */, 4015 GSSCredential.INITIATE_ONLY /* init context */); 4017 print("GSSCredential created for " + 4018 cred.getName().toString()); 4019 print("Credential lifetime (sec)=" + 4020 cred.getRemainingLifetime()); 4021 } catch (GSSException e) { 4022 print("GSS-API error in credential acquisition: " 4023 + e.getMessage()); 4024 ... 4025 ... 4026 } 4028 ... 4029 ... 4030 } 4032 /** 4033 * Does the security context establishment with the 4034 * server. 4035 */ 4036 private void establishContext() { 4038 byte[] inToken = new byte[0]; 4039 byte[] outToken = null; 4041 try { 4043 GSSName peer = mgr.createName(serviceName, 4044 GSSName.NT_HOSTBASED_SERVICE); 4045 context = mgr.createContext(peer, mech, gssCred, 4046 GSSContext.INDEFINITE_LIFETIME/*lifetime*/); 4048 // Will need to support confidentiality 4049 context.requestConf(true); 4051 while (!context.isEstablished()) { 4053 outToken = context.initSecContext(inToken, 0, 4054 inToken.length); 4056 if (outToken != null) 4057 writeGSSToken(outToken); 4059 if (!context.isEstablished()) 4060 inToken = readGSSToken(); 4061 } 4062 GSSName peer = context.getSrcName(); 4063 print("Security context established with " + peer + 4064 " using underlying mechanism " + mech.toString()); 4065 } catch (GSSException e) { 4066 print("GSS-API error during context establishment: " 4067 + e.getMessage()); 4068 ... 4069 ... 4070 } 4072 ... 4073 ... 4074 } 4076 /** 4077 * Sends some data to the server and reads back the 4078 * response. 4079 */ 4080 private void doCommunication() { 4081 byte[] inToken = null; 4082 byte[] outToken = null; 4083 byte[] buffer; 4085 // Container for multiple input-output arguments to and 4086 // from the per-message routines (e.g., wrap/unwrap). 4087 MessageProp messgInfo = new MessageProp(); 4089 try { 4091 /* 4092 * Now send some bytes to the server to be 4093 * processed. They will be integrity protected but 4094 * not encrypted for privacy. 4095 */ 4097 buffer = readFromFile(); 4099 // Set privacy to false and use the default QOP 4100 messgInfo.setPrivacy(false); 4102 outToken = context.wrap(buffer, 0, buffer.length, 4103 messgInfo); 4105 writeGSSToken(outToken); 4107 /* 4108 * Now read the response from the server. 4109 */ 4111 inToken = readGSSToken(); 4112 buffer = context.unwrap(inToken, 0, 4113 inToken.length, messgInfo); 4114 // All ok if no exception was thrown! 4116 GSSName peer = context.getSrcName(); 4118 print("Message from " + peer.toString() 4119 + " arrived."); 4120 print("Was it encrypted? " + 4121 messgInfo.getPrivacy()); 4122 print("Duplicate Token? " + 4123 messgInfo.isDuplicateToken()); 4124 print("Old Token? " + 4125 messgInfo.isOldToken()); 4126 print("Unsequenced Token? " + 4127 messgInfo.isUnseqToken()); 4128 print("Gap Token? " + 4129 messgInfo.isGapToken()); 4131 ... 4132 ... 4134 } catch (GSSException e) { 4135 print("GSS-API error in per-message calls: " 4136 + e.getMessage()); 4137 ... 4138 ... 4140 } 4142 ... 4144 ... 4146 } // end of doCommunication method 4148 ... 4149 ... 4151 } // end of class SimpleClient 4153 8.2 Simple GSS Context Acceptor 4155 import org.ietf.jgss.*; 4157 /** 4158 * This is a partial sketch for a simple server program that acts 4159 * as a GSS context acceptor. It illustrates how to use the Java 4160 * bindings for the GSS-API specified in 4161 * Generic Security Service API Version 2 : Java bindings 4162 * 4163 * This code sketch assumes the existence of a GSS-API 4164 * implementation that supports the mechanisms that it will need 4165 * and is present as a library package (org.ietf.jgss) either as 4166 * part of the standard JRE or in the CLASSPATH the application 4167 * specifies. 4168 */ 4170 import org.ietf.jgss.*; 4172 public class SimpleServer { 4174 private String serviceName; 4175 private GSSName name; 4176 private GSSCredential cred; 4178 private GSSManager mgr; 4180 ... 4181 ... 4183 /** 4184 * Wait for client connections, establish security contexts 4185 * and provide service. 4186 */ 4187 private void loop() { 4189 ... 4190 ... 4192 mgr = GSSManager.getInstance(); 4194 name = mgr.createName(serviceName, 4195 GSSName.NT_HOSTBASED_SERVICE); 4197 cred = mgr.createCredential(name, 4198 GSSCredential.INDEFINITE_LIFETIME, 4199 null, 4200 GSSCredential.ACCEPT_ONLY); 4202 // Loop infinitely 4203 while (true) { 4204 Socket s = serverSock.accept(); 4206 // Start a new thread to serve this connection 4207 Thread serverThread = new ServerThread(s); 4208 serverThread.start(); 4210 } 4211 } 4213 /** 4214 * Inner class ServerThread whose run() method provides the 4215 * secure service to a connection. 4216 */ 4218 private class ServerThread extends Thread { 4220 ... 4221 ... 4223 /** 4224 * Deals with the connection from one client. It also 4225 * handles all GSSException's thrown while talking to 4226 * this client. 4227 */ 4228 public void run() { 4230 byte[] inToken = null; 4231 byte[] outToken = null; 4232 byte[] buffer; 4234 GSSName peer; 4236 // Container for multiple input-output arguments to 4237 // and from the per-message routines 4238 // (i.e. wrap/unwrap). 4239 MessageProp supplInfo = new MessageProp(); 4241 GSSContext secContext = null; 4243 try { 4245 // Now do the context establishment loop 4247 GSSContext context = mgr.createContext(cred); 4249 while (!context.isEstablished()) { 4250 inToken = readGSSToken(); 4252 outToken = context.acceptSecContext(inToken, 4253 0, inToken.length); 4255 if (outToken != null) 4256 writeGSSToken(outToken); 4258 } 4260 // SimpleServer wants confidentiality to be 4261 // available. Check for it. 4262 if (!context.getConfState()){ 4263 ... 4264 ... 4265 } 4267 GSSName peer = context.getSrcName(); 4268 Oid mech = context.getMech(); 4269 print("Security context established with " + 4270 peer.toString() + 4271 " using underlying mechanism " + 4272 mech.toString() + 4273 " from Provider " + 4274 context.getProvider().getName()); 4276 // Now read the bytes sent by the client to be 4277 // processed. 4278 inToken = readGSSToken(); 4280 // Unwrap the message 4281 buffer = context.unwrap(inToken, 0, 4282 inToken.length, supplInfo); 4283 // All ok if no exception was thrown! 4285 // Print other supplementary per-message status 4286 // information 4288 print("Message from " + 4289 peer.toString() + " arrived."); 4290 print("Was it encrypted? " + 4291 supplInfo.getPrivacy()); 4292 print("Duplicate Token? " + 4293 supplInfo.isDuplicateToken()); 4294 print("Old Token? " + supplInfo.isOldToken()); 4295 print("Unsequenced Token? " + 4296 supplInfo.isUnseqToken()); 4298 print("Gap Token? " + supplInfo.isGapToken()); 4300 /* 4301 * Now process the bytes and send back an 4302 * encrypted response. 4303 */ 4305 buffer = serverProcess(buffer); 4307 // Encipher it and send it across 4309 supplInfo.setPrivacy(true); // privacy requested 4310 supplInfo.setQOP(0); // default QOP 4311 outToken = context.wrap(buffer, 0, buffer.length, 4312 supplInfo); 4313 writeGSSToken(outToken); 4315 } catch (GSSException e) { 4316 print("GSS-API Error: " + e.getMessage()); 4317 // Alternatively, could call e.getMajorMessage() 4318 // and e.getMinorMessage() 4319 print("Abandoning security context."); 4321 ... 4322 ... 4324 } 4326 ... 4327 ... 4329 } // end of run method in ServerThread 4331 } // end of inner class ServerThread 4333 ... 4334 ... 4336 } // end of class SimpleServer 4338 9. Security Considerations 4340 The Java language security model allows platform providers to have 4341 policy based fine-grained access control over any resource that an 4342 application wants. When using a Java security manager (such as, but 4343 not limited to, the case of applets running in browsers) the 4344 application code is in a sandbox by default. 4346 Administrators of the platform JRE determine what permissions, if 4347 any, are to be given to source from different codebases. Thus the 4348 administrator has to be aware of any special requirements that the 4349 GSS provider might have for system resources. For instance, a 4350 Kerberos provider might wish to make a network connection to the KDC 4351 to obtain initial credentials. This would not be allowed under the 4352 sandbox unless the administrator had granted permissions for this. 4353 Also note that this granting and checking of permissions happens 4354 transparently to the application and is outside the scope of this 4355 document. 4357 The Java language allows administrators to pre-configure a list of 4358 security service providers in the /lib/security/java.security 4359 file. At runtime, the system approaches these providers in order of 4360 preference when looking for security related services. Applications 4361 have a means to modify this list through methods in the "Security" 4362 class in the "java.security" package. However, since these 4363 modifications would be visible in the entire JVM and thus affect all 4364 code executing in it, this operation is not available in the sandbox 4365 and requires special permissions to perform. Thus when a GSS 4366 application has special needs that are met by a particular security 4367 provider, it has two choices: 4369 1) To install the provider on a JVM wide basis using the 4370 java.security.Security class and then depend on the system to find 4371 the right provider automatically when the need arises. (This would 4372 require the application to be granted a "insertProvider 4373 SecurityPermission".) 4375 2) To pass an instance of the provider to the local instance of 4376 GSSManager so that only factory calls going through that GSSManager 4377 use the desired provider. (This would not require any permissions.) 4379 10. IANA Considerations 4381 This document has no IANA considerations currently. 4383 11. Acknowledgments 4385 This proposed API leverages earlier work performed by the IETF's CAT 4386 WG as outlined in both RFC 2743 and RFC 2744. Many conceptual 4387 definitions, implementation directions, and explanations have been 4388 included from these documents. 4390 We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael 4391 Saltz and other members of Sun's development team for their helpful 4392 input, comments and suggestions. 4394 We would also like to thank Joe Salowey, and Michael Smith for many 4395 insightful ideas and suggestions that have contributed to this 4396 document. 4398 12. References 4400 12.1 Normative References 4402 [RFC2853] Kabat, J. and M. Upadhyay, "Generic Security Service 4403 Application Program Interface : Java Bindings", RFC 2853, 4404 June 2000. 4406 [GSSAPIv2-UPDATE] 4407 Linn, J., "Generic Security Service Application Program 4408 Interface, Version 2, Update 1", RFC 2743, January 2000. 4410 [GSSAPI-Cbind] 4411 Wray, J., "Generic Security Service API Version 2 : 4412 C-bindings", RFC 2744, January 2000. 4414 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4415 Requirement Levels", BCP 14, RFC 2119, March 1997. 4417 [RFC4121] Zhu, L. and S. Hartman, "The Kerberos Version 5 Generic 4418 Security Service Application Program Interface (GSS-API) 4419 Mechanism: Version 2", RFC 4121, July 2005. 4421 [RFC2025] Adams, C., "The Simple Public-Key GSS-API Mechanism", 4422 RFC 2025, October 1996. 4424 12.2 Informative References 4426 [JLS] Gosling, J., "The Java Language Specification", JLS langspec. 4428 Authors' Addresses 4430 Mayank D. Upadhyay 4431 Google Inc. 4432 1600 Amphitheatre Parkway 4433 Mountain View, CA 94043 4434 USA 4436 Email: mayank+ietf-2853@google.com 4437 Seema Malkani 4438 Sun Microsystems, Inc. 4439 4140 Network Circle 4440 Santa Clara, CA 95054 4441 USA 4443 Email: Seema.Malkani@sun.com 4445 Intellectual Property Statement 4447 The IETF takes no position regarding the validity or scope of any 4448 Intellectual Property Rights or other rights that might be claimed to 4449 pertain to the implementation or use of the technology described in 4450 this document or the extent to which any license under such rights 4451 might or might not be available; nor does it represent that it has 4452 made any independent effort to identify any such rights. Information 4453 on the procedures with respect to rights in RFC documents can be 4454 found in BCP 78 and BCP 79. 4456 Copies of IPR disclosures made to the IETF Secretariat and any 4457 assurances of licenses to be made available, or the result of an 4458 attempt made to obtain a general license or permission for the use of 4459 such proprietary rights by implementers or users of this 4460 specification can be obtained from the IETF on-line IPR repository at 4461 http://www.ietf.org/ipr. 4463 The IETF invites any interested party to bring to its attention any 4464 copyrights, patents or patent applications, or other proprietary 4465 rights that may cover technology that may be required to implement 4466 this standard. Please address the information to the IETF at 4467 ietf-ipr@ietf.org. 4469 Disclaimer of Validity 4471 This document and the information contained herein are provided on an 4472 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4473 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 4474 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 4475 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 4476 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4477 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4479 Copyright Statement 4481 Copyright (C) The Internet Society (2006). This document is subject 4482 to the rights, licenses and restrictions contained in BCP 78, and 4483 except as set forth therein, the authors retain all their rights. 4485 Acknowledgment 4487 Funding for the RFC Editor function is currently provided by the 4488 Internet Society.