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