Summary
-------

Implement a client-side native library that translates calls from GSS-API to Microsoft Windows Security Support Provider Interface (SSPI).

Goals
-----

1. Establish a GSS-API security context and secure communication channel using default credentials without requiring any additional configuration.
2. Provide support for the Kerberos 5 and SPNEGO GSS-API mechanisms.

Non-Goals
---------

It is not a goal of this JEP to provide a library that supports all features of GSS-API. Specifically, it is not a goal to provide the following features:

1. Client-side GSS-API functions not using the default credentials.
2. Delegation of client-side credentials to server.
3. Server-side GSS-API functions.

Motivation
------

The [Generic Security Service Application Program Interface][gssapi] (GSS-API) is a generalized API that offers application programmers uniform access to security services implemented over a variety of underlying cryptographic mechanisms (for example, Kerberos 5).  The JDK contains two GSS-API implementations, one is implemented in pure Java and the other is implemented as a native GSS-API bridge.

In order to use GSS-API to establish a security context with a peer, initial credentials are required.  On the client side, the credentials are usually acquired through a login process.  On Windows, this happens when a domain user logs in to a Windows Active Directory server.  The credentials are then stored in a secure memory location called an LSA cache.

Until recently, as long as the [`allowtgtsessionkey` registry entry][allowtgtsessionkey] was set, the pure Java GSS-API implementation in the JDK was able to read the credentials in the LSA cache as a ticket and an accompanying session key, and use it to establish a security context.  However, with the introduction of the Windows 10 [Credential Guard feature][credguard], the session key of the credentials is not externally available anymore.  Without the session key, a Kerberos client must login itself by asking users for a password.  This prevents Kerberos from being used as a Single Sign-on mechanism.

Microsoft offers the Security Support Provider Interface (SSPI) to perform authentication and secure communication.  SSPI is able to use the credentials in the LSA cache.  The tokens generated and accepted by SSPI are mostly compatible with GSS-API, but the function calls are different.

The JDK's native GSS-API bridge is able to connect to an existing native GSS-API library.  If we create a native GSS-API library that can translates calls from GSS-API to SSPI, a Java GSS-API application will be able to make use of SSPI functions inside Windows.

Description
-----------

Create a native GSS-API library which, when loaded by the native GSS-API bridge in the JDK, is able to acquire default credentials, establish a security context, and perform secure communications, by calling related SSPI functions.

Alternatives
------------

Two approaches for the JDK to call into SSPI were considered:

1.  Supplement the pure Java implementation with JNI calls into SSPI.
2.  Create a pure native library (independent of Java) that translates GSS-API calls to SSPI.

We chose the second approach for these reasons:

1.  For application developers. Not only can a Java GSS-API application make use of SSPI functions in Windows through this new library, but a native GSS-API application written in C can also directly use it, since it exposes the standard GSS-API C bindings.
2.  For testing. There are many existing applications and libraries that call native GSS-API that we can leverage for testing purposes.
3.  For code reviewing. Since it is written in plain C without any JNI calls, it is more understandable to developers who are not familiar with Java but have expertise in SSPI and GSS-API.

Testing
-------

Tests should cover these cases on the client side:

1.  Windows 10 with Credentials Guard turned on or off.
2.  Earlier versions of Windows with the `allowtgtsessionkey` registry key set or not set.

A Java client using this new library should be able to interoperate with:

1.  A Java server using the pure Java GSS-API library that performs security context establishment and secure communications.
2.  A server-side SSPI application that performs security context establishment and secure communications.
3.  Existing Windows components like the Internet Information Server or Active Directory server.

Risks and Assumptions
---------------------

Although SSPI and GSS-API are mostly compatible, there are small differences.  There may also be differences between the features supported by the Kerberos 5 implementation on Windows and other vendors (for example, from MIT krb5).


[gssapi]: https://tools.ietf.org/html/rfc2743
[allowtgtsessionkey]: https://support.microsoft.com/en-za/help/308339/registry-key-to-allow-session-keys-to-be-sent-in-kerberos-ticket-grant
[credguard]: https://docs.microsoft.com/en-gb/windows/security/identity-protection/credential-guard/credential-guard