Generic Security Service API Version 2: Java Bindings Update
draft-ietf-kitten-rfc5653bis-05

quot;Old Token? "  + supplInfo.isOldToken());
                   print("Unsequenced Token? " +
                           supplInfo.isUnseqToken());
                   print("Gap Token? "  + supplInfo.isGapToken());

                   /*
                    * Now process the bytes and send back an
                    * encrypted response.
                    */

                   buffer = serverProcess(buffer);

                   // Encipher it and send it across

                   supplInfo.setPrivacy(true); // privacy requested
                   supplInfo.setQOP(0); // default QOP
                   outToken = context.wrap(buffer, 0, buffer.length,

Upadhyay, et al.        Expires February 5, 2018               [Page 88]
Internet-Draft       draft-ietf-kitten-rfc5653bis-05         August 2017

                                              supplInfo);
                   writeGSSToken(outToken);

               } catch (GSSException e) {
                   print("GSS-API Error: " + e.getMessage());
                   // Alternatively, could call e.getMajorMessage()
                   // and e.getMinorMessage()

                   // If the exception contains an output token,
                   // it should be sent to the initiator.
                   byte[] outTok = e.getOutputToken();
                   if (outTok != null) {
                       writeGSSToken(outTok);
                   }
                   print("Abandoning security context.");
                   ...
                   ...
               }
               ...
               ...
           } // end of run method in ServerThread

       } // end of inner class ServerThread

       ...
       ...

   } // end of class SimpleServer
   <CODE ENDS>

8.  Security Considerations

   The Java language security model allows platform providers to have
   policy-based fine-grained access control over any resource that an
   application wants.  When using a Java security manager (such as, but
   not limited to, the case of applets running in browsers) the
   application code is in a sandbox by default.

   Administrators of the platform JRE determine what permissions, if
   any, are to be given to source from different codebases.  Thus, the
   administrator has to be aware of any special requirements that the
   GSS provider might have for system resources.  For instance, a
   Kerberos provider might wish to make a network connection to the Key
   Distribution Center (KDC) to obtain initial credentials.  This would
   not be allowed under the sandbox unless the administrator had granted
   permissions for this.  Also, note that this granting and checking of
   permissions happens transparently to the application and is outside
   the scope of this document.

Upadhyay, et al.        Expires February 5, 2018               [Page 89]
Internet-Draft       draft-ietf-kitten-rfc5653bis-05         August 2017

   The Java language allows administrators to pre-configure a list of
   security service providers in the <JRE>/lib/security/java.security
   file.  At runtime, the system approaches these providers in order of
   preference when looking for security related services.  Applications
   have a means to modify this list through methods in the "Security"
   class in the "java.security" package.  However, since these
   modifications would be visible in the entire Java Virtual Machine
   (JVM) and thus affect all code executing in it, this operation is not
   available in the sandbox and requires special permissions to perform.
   Thus, when a GSS application has special needs that are met by a
   particular security provider, it has two choices:

   1) To install the provider on a JVM-wide basis using the
      java.security.Security class and then depend on the system to find
      the right provider automatically when the need arises.  (This
      would require the application to be granted a "insertProvider
      SecurityPermission".)

   2) To pass an instance of the provider to the local instance of
      GSSManager so that only factory calls going through that
      GSSManager use the desired provider.  (This would not require any
      permissions.)

9.  IANA Considerations

   This document has no actions for IANA.

10.  Acknowledgments

   This proposed API leverages earlier work performed by the IETF's CAT
   WG as outlined in both RFC 2743 [RFC2743] and RFC 2744 [RFC2744].
   Many conceptual definitions, implementation directions, and
   explanations have been included from these documents.

   We would like to thank Mike Eisler, Lin Ling, Ram Marti, Michael
   Saltz, and other members of Sun's development team for their helpful
   input, comments, and suggestions.

   We would also like to thank Joe Salowey, and Michael Smith for many
   insightful ideas and suggestions that have contributed to this
   document.

11.  Changes since RFC 5653

   This document has following changes:

   1) New error token embedded in GSSException

Upadhyay, et al.        Expires February 5, 2018               [Page 90]
Internet-Draft       draft-ietf-kitten-rfc5653bis-05         August 2017

      There is a design flaw in the initSecContext and acceptSecContext
      methods of the GSSContext class defined in Generic Security
      Service API Version 2: Java Bindings Update [RFC5653].

      The methods could either return a token (possibly null if no more
      tokens are needed) when the call succeeds or throw a GSSException
      if there is a failure, but NOT both.  On the other hand, the C
      bindings of GSS-API [RFC2744] can return both, that is to say, a
      call to the GSS_Init_sec_context() function can return a major
      status code, and at the same time, fill in the output_token
      argument if there is one.

      Without the ability to emit an error token when there is a
      failure, a Java application has no mechanism to tell the other
      side what the error is.  For example, a "reject" NegTokenResp
      token can never be transmitted for the SPNEGO mechanism [RFC4178].

      While a Java method can never return a value and throw an
      exception at the same time, we can embed the error token inside
      the exception so that the caller has a chance to retrieve it.
      This update adds a new GSSException constructor to include this
      token inside a GSSException object, and a getOutputToken() method
      to retrieve the token.  The specification for the initSecContext
      and acceptSecContext methods are updated to describe the new
      behavior.  Various examples are also updated.

      This is a compatible change.  New JGSS programs should make use of
      this new feature but it is not mandatory.

   2) Removing stream-based GSSContext methods

      The overloaded methods of GSSContext that use input and output
      streams as the means to convey authentication and per-message GSS-
      API tokens as described in Section 5.15 of RFC 5653 [RFC5653] are
      removed in this update as the wire protocol should be defined by
      an application and not a library.  It's also impossible to
      implement these methods correctly when the token has no self-
      framing (where the end cannot be determined) or the library has no
      knowledge of the token format (for example, as a bridge talking to
      another GSS library).  These methods include initSecContext
      (Section 7.4.5 of RFC 5653 [RFC5653]), acceptSecContext
      (Section 7.4.9 of RFC 5653 [RFC5653]), wrap (Section 7.4.15 of RFC
      5653 [RFC5653]), unwrap (Section 7.4.17 of RFC 5653 [RFC5653]),
      getMIC (Section 7.4.19 of RFC 5653 [RFC5653]), and verifyMIC
      (Section 7.4.21 of RFC 5653 [RFC5653]).

Upadhyay, et al.        Expires February 5, 2018               [Page 91]
Internet-Draft       draft-ietf-kitten-rfc5653bis-05         August 2017

12.  Changes since RFC 2853

   This document has following changes:

   1) Major GSS Status Code Constant Values

      RFC 2853 listed all the GSS status code values in two different
      sections: section 4.12.1 defined numeric values for them, and
      section 6.8.1 defined them as static constants in the GSSException
      class without assigning any values.  Due to an inconsistent
      ordering between these two sections, all of the GSS major status
      codes resulted in misalignment, and a subsequent disagreement
      between deployed implementations.

      This document defines the numeric values of the GSS status codes
      in both sections, while maintaining the original ordering from
      section 6.8.1 of RFC 2853 [RFC2853], and obsoletes the GSS status
      code values defined in section 4.12.1.  The relevant sections in
      this document are sections 4.12.1 and 6.8.1.

   2) GSS Credential Usage Constant Values

      RFC 2853 section 6.3.2 defines static constants for the
      GSSCredential usage flags.  However, the values of these constants
      were not defined anywhere in RFC 2853 [RFC2853].

      This document defines the credential usage values in section
      6.3.1.  The original ordering of these values from section 6.3.2
      of RFC 2853 [RFC2853] is maintained.

   3) GSS Host-Based Service Name

      RFC 2853 [RFC2853], section 6.2.2, defines the static constant for
      the GSS host-based service OID NT_HOSTBASED_SERVICE, using a
      deprecated OID value.

      This document updates the NT_HOSTBASED_SERVICE OID value in
      section 6.2.1 to be consistent with the C-bindings in RFC 2744
      [RFC2744].

13.  References

13.1.  Normative References

   [RFC2025]  Adams, C., "The Simple Public-Key GSS-API Mechanism
              (SPKM)", RFC 2025, DOI 10.17487/RFC2025, October 1996,
              <http://www.rfc-editor.org/info/rfc2025>.

Upadhyay, et al.        Expires February 5, 2018               [Page 92]
Internet-Draft       draft-ietf-kitten-rfc5653bis-05         August 2017

   [RFC2743]  Linn, J., "Generic Security Service Application Program
              Interface Version 2, Update 1", RFC 2743,
              DOI 10.17487/RFC2743, January 2000,
              <http://www.rfc-editor.org/info/rfc2743>.

   [RFC2744]  Wray, J., "Generic Security Service API Version 2 :
              C-bindings", RFC 2744, DOI 10.17487/RFC2744, January 2000,
              <http://www.rfc-editor.org/info/rfc2744>.

   [RFC2853]  Kabat, J. and M. Upadhyay, "Generic Security Service API
              Version 2 : Java Bindings", RFC 2853,
              DOI 10.17487/RFC2853, June 2000,
              <http://www.rfc-editor.org/info/rfc2853>.

   [RFC4121]  Zhu, L., Jaganathan, K., and S. Hartman, "The Kerberos
              Version 5 Generic Security Service Application Program
              Interface (GSS-API) Mechanism: Version 2", RFC 4121,
              DOI 10.17487/RFC4121, July 2005,
              <http://www.rfc-editor.org/info/rfc4121>.

   [RFC4178]  Zhu, L., Leach, P., Jaganathan, K., and W. Ingersoll, "The
              Simple and Protected Generic Security Service Application
              Program Interface (GSS-API) Negotiation Mechanism",
              RFC 4178, DOI 10.17487/RFC4178, October 2005,
              <http://www.rfc-editor.org/info/rfc4178>.

   [RFC5653]  Upadhyay, M. and S. Malkani, "Generic Security Service API
              Version 2: Java Bindings Update", RFC 5653,
              DOI 10.17487/RFC5653, August 2009,
              <http://www.rfc-editor.org/info/rfc5653>.

13.2.  Informative References

   [JLS]      Gosling, J., Joy, B., Steele, G., and G. Bracha, "The Java
              Language Specification", Third Edition, 2005,
              <http://java.sun.com/docs/books/jls/>.

Authors' Addresses

   Mayank D. Upadhyay
   Google Inc.
   1600 Amphitheatre Parkway
   Mountain View, CA  94043
   USA

   Email: m.d.upadhyay+ietf@gmail.com

Upadhyay, et al.        Expires February 5, 2018               [Page 93]
Internet-Draft       draft-ietf-kitten-rfc5653bis-05         August 2017

   Seema Malkani
   ActivIdentity Corp.
   6623 Dumbarton Circle
   Fremont, California  94555
   USA

   Email: Seema.Malkani@gmail.com

   Wang Weijun
   Oracle
   Building No. 24, Zhongguancun Software Park
   Beijing  100193
   China

   Email: weijun.wang@oracle.com

Upadhyay, et al.        Expires February 5, 2018               [Page 94]