|
|
|
|
@ -1,305 +0,0 @@
|
|
|
|
|
// ========================================================================
|
|
|
|
|
// Copyright (c) 1995-2017 Mort Bay Consulting Pty. Ltd.
|
|
|
|
|
// ========================================================================
|
|
|
|
|
// All rights reserved. This program and the accompanying materials
|
|
|
|
|
// are made available under the terms of the Eclipse Public License v1.0
|
|
|
|
|
// and Apache License v2.0 which accompanies this distribution.
|
|
|
|
|
//
|
|
|
|
|
// The Eclipse Public License is available at
|
|
|
|
|
// http://www.eclipse.org/legal/epl-v10.html
|
|
|
|
|
//
|
|
|
|
|
// The Apache License v2.0 is available at
|
|
|
|
|
// http://www.opensource.org/licenses/apache2.0.php
|
|
|
|
|
//
|
|
|
|
|
// You may elect to redistribute this code under either of these licenses.
|
|
|
|
|
// ========================================================================
|
|
|
|
|
|
|
|
|
|
How to build NPN
|
|
|
|
|
================
|
|
|
|
|
|
|
|
|
|
[[npn]]
|
|
|
|
|
=
|
|
|
|
|
|
|
|
|
|
[[npn-introduction]]
|
|
|
|
|
== Configuring NPN
|
|
|
|
|
|
|
|
|
|
The Jetty project provides an implementation of the Transport Layer
|
|
|
|
|
Security (TLS) extension for Next Protocol Negotiation (NPN) for OpenJDK
|
|
|
|
|
7 (but not for OpenJDK 8 or greater - see xref:alpn-chapter[] for
|
|
|
|
|
using a TLS protocol negotiation extension with OpenJDK 8 or greater).
|
|
|
|
|
NPN allows the application layer to negotiate which protocol to use over
|
|
|
|
|
the secure connection.
|
|
|
|
|
|
|
|
|
|
NPN currently negotiates using SPDY as an application level protocol on
|
|
|
|
|
port 443, and also negotiates the SPDY version. However, NPN is not
|
|
|
|
|
SPDY-specific in any way. Jetty's NPN implementation, although hosted
|
|
|
|
|
under the umbrella of the Jetty project, is independent of Jetty (the
|
|
|
|
|
servlet container); you can use it in any other Java network server.
|
|
|
|
|
|
|
|
|
|
[[npn-starting]]
|
|
|
|
|
== Starting the JVM
|
|
|
|
|
|
|
|
|
|
To enable NPN support, start the JVM as follows:
|
|
|
|
|
|
|
|
|
|
[source, plain, subs="{sub-order}"]
|
|
|
|
|
----
|
|
|
|
|
java -Xbootclasspath/p:<path_to_npn_boot_jar> ...
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
where `path_to_npn_boot_jar` is the path on the file system for the NPN
|
|
|
|
|
Boot Jar file, for example, one at the Maven coordinates
|
|
|
|
|
org.mortbay.jetty.npn:npn-boot.
|
|
|
|
|
|
|
|
|
|
Be aware that the current versions of the npn packages no longer align
|
|
|
|
|
with Jetty versions. Look at the dates in those file paths before
|
|
|
|
|
looking at the version number.
|
|
|
|
|
|
|
|
|
|
[[npn-osgi]]
|
|
|
|
|
=== Starting in OSGi
|
|
|
|
|
|
|
|
|
|
To use NPN in an OSGi environment, in addition to putting the NPN jar on
|
|
|
|
|
the boot classpath for the container, you will also need to deploy the
|
|
|
|
|
jetty-osgi-npn jar. This jar contains a Fragment-Host directive that
|
|
|
|
|
ensures the NPN classes will be available from the system bundle.
|
|
|
|
|
|
|
|
|
|
You can download the jetty-osgi-npn jar from maven central:
|
|
|
|
|
http://central.maven.org/maven2/org/eclipse/jetty/osgi/jetty-osgi-npn/
|
|
|
|
|
|
|
|
|
|
[[npn-understanding]]
|
|
|
|
|
== Understanding the NPN API
|
|
|
|
|
|
|
|
|
|
Applications need to interact with NPN TLS extension protocol
|
|
|
|
|
negotiations. For example, server applications need to know whether the
|
|
|
|
|
client supports NPN, and client applications needs to know the list of
|
|
|
|
|
protocols the server supports, and so on.
|
|
|
|
|
|
|
|
|
|
To implement this interaction, Jetty's NPN implementation provides an
|
|
|
|
|
API to applications, hosted at Maven coordinates
|
|
|
|
|
org.eclipse.jetty.npn:npn-api. You need to declare this dependency as
|
|
|
|
|
provided, because the npn-boot Jar already includes it (see the previous
|
|
|
|
|
section), and it is therefore available in the boot classpath.
|
|
|
|
|
|
|
|
|
|
The API consists of a single class,
|
|
|
|
|
`org.eclipse.jetty.npn.NextProtoNego`, and applications need to register
|
|
|
|
|
instances of SSLSocket or SSLEngine with a ClientProvider or
|
|
|
|
|
ServerProvider (depending on whether the application is a client or
|
|
|
|
|
server application). Refer to NextProtoNego Javadocs and to the examples
|
|
|
|
|
below for further details about client and server provider methods.
|
|
|
|
|
|
|
|
|
|
[[client-example]]
|
|
|
|
|
== Client Example
|
|
|
|
|
|
|
|
|
|
[source, java, subs="{sub-order}"]
|
|
|
|
|
----
|
|
|
|
|
SSLContext sslContext = ...;
|
|
|
|
|
final SSLSocket sslSocket = (SSLSocket)context.getSocketFactory().createSocket("localhost", server.getLocalPort());
|
|
|
|
|
|
|
|
|
|
NextProtoNego.put(sslSocket, new NextProtoNego.ClientProvider()
|
|
|
|
|
{
|
|
|
|
|
@Override
|
|
|
|
|
public boolean supports()
|
|
|
|
|
{
|
|
|
|
|
return true;
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public void unsupported()
|
|
|
|
|
{
|
|
|
|
|
NextProtoNego.remove(sslSocket);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public String selectProtocol(List<String> protocols)
|
|
|
|
|
{
|
|
|
|
|
NextProtoNego.remove(sslSocket);
|
|
|
|
|
return protocols.get(0);
|
|
|
|
|
}
|
|
|
|
|
});
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The NPN implementation calls `NextProtoNego.ClientProvider` methods
|
|
|
|
|
`supports()`, `unsupported()` and `selectProtocol(List<String>)`, so
|
|
|
|
|
that the client application can:
|
|
|
|
|
|
|
|
|
|
* decide whether to support NPN.
|
|
|
|
|
* know whether the server supports NPN.
|
|
|
|
|
* select one of the protocols the server supports.
|
|
|
|
|
|
|
|
|
|
[[server-example]]
|
|
|
|
|
== Server Example
|
|
|
|
|
|
|
|
|
|
The example for SSLEngine is identical, and you just need to replace the
|
|
|
|
|
SSLSocket instance with an SSLEngine instance.
|
|
|
|
|
|
|
|
|
|
[source, java, subs="{sub-order}"]
|
|
|
|
|
----
|
|
|
|
|
final SSLSocket sslSocket = ...;
|
|
|
|
|
NextProtoNego.put(sslSocket, new NextProtoNego.ServerProvider()
|
|
|
|
|
{
|
|
|
|
|
@Override
|
|
|
|
|
public void unsupported()
|
|
|
|
|
{
|
|
|
|
|
NextProtoNego.remove(sslSocket);
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public List<String> protocols()
|
|
|
|
|
{
|
|
|
|
|
return Arrays.asList("http/1.1");
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@Override
|
|
|
|
|
public void protocolSelected(String protocol)
|
|
|
|
|
{
|
|
|
|
|
NextProtoNego.remove(sslSocket);
|
|
|
|
|
System.out.println("Protocol Selected is: " + protocol);
|
|
|
|
|
}
|
|
|
|
|
});
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
The NPN implementation calls `NextProtoNego.ServerProvider` methods
|
|
|
|
|
`unsupported()`, `protocols()` and `protocolSelected(String),` so that
|
|
|
|
|
the server application can:
|
|
|
|
|
|
|
|
|
|
* know whether the client supports NPN.
|
|
|
|
|
* provide the list of protocols the server supports.
|
|
|
|
|
* know which protocol the client chooses.
|
|
|
|
|
|
|
|
|
|
[[npn-implementation]]
|
|
|
|
|
== Implementation Details
|
|
|
|
|
|
|
|
|
|
It is common that the NextProtoNego.ServerProvider and the
|
|
|
|
|
NextProtoNego.ClientProvider are implemented as (anonymous) inner
|
|
|
|
|
classes, and that their methods' implementations require references to
|
|
|
|
|
the the sslSocket (or sslEngine), either directly or indirectly.
|
|
|
|
|
|
|
|
|
|
Since the NextProtoNego class holds [sslSocket/sslEngine, provider]
|
|
|
|
|
pairs in a `WeakHashMap`, if the value (that is, the provider
|
|
|
|
|
implementation) holds a strong (even indirect) reference to the key,
|
|
|
|
|
then the `WeakHashMap` entries are never removed, leading to a memory
|
|
|
|
|
leak.
|
|
|
|
|
|
|
|
|
|
It is important that implementations of `NextProtoNego.ServerProvider`
|
|
|
|
|
and `NextProtoNego.ClientProvider` remove the `sslSocket` or `sslEngine`
|
|
|
|
|
when the negotiation is complete, like shown in the examples above.
|
|
|
|
|
|
|
|
|
|
Be aware that declaring the SslConnection as a final local variable and
|
|
|
|
|
referencing it from within the anonymous NextProtoNego.ServerProvider
|
|
|
|
|
class generates a hidden field in the anonymous inner class, that may
|
|
|
|
|
cause a memory leak if the implementation does not call
|
|
|
|
|
`NextProtoNego.remove()`.
|
|
|
|
|
|
|
|
|
|
[[npn-tests]]
|
|
|
|
|
== Unit Tests
|
|
|
|
|
|
|
|
|
|
You can write and run unit tests that use the NPN implementation. The
|
|
|
|
|
solution that we use with Maven is to specify an additional command line
|
|
|
|
|
argument to the Surefire plugin:
|
|
|
|
|
|
|
|
|
|
[source, xml, subs="{sub-order}"]
|
|
|
|
|
----
|
|
|
|
|
<project>
|
|
|
|
|
|
|
|
|
|
<properties>
|
|
|
|
|
<npn-version>1.1.1.v20121030</npn-version>
|
|
|
|
|
</properties>
|
|
|
|
|
|
|
|
|
|
<build>
|
|
|
|
|
<plugins>
|
|
|
|
|
<plugin>
|
|
|
|
|
<artifactId>maven-surefire-plugin</artifactId>
|
|
|
|
|
<configuration>
|
|
|
|
|
<argLine>
|
|
|
|
|
-Xbootclasspath/p:${settings.localRepository}/org/mortbay/jetty/npn/npn-boot/${npn-version}/npn-boot-${npn-version}.jar
|
|
|
|
|
</argLine>
|
|
|
|
|
</configuration>
|
|
|
|
|
</plugin>
|
|
|
|
|
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
</plugins>
|
|
|
|
|
</build>
|
|
|
|
|
|
|
|
|
|
...
|
|
|
|
|
|
|
|
|
|
</project>
|
|
|
|
|
----
|
|
|
|
|
|
|
|
|
|
[[npn-debugging]]
|
|
|
|
|
== Debugging
|
|
|
|
|
|
|
|
|
|
You can enable debug logging for the NPN implementation in this way:
|
|
|
|
|
|
|
|
|
|
....
|
|
|
|
|
NextProtoNego.debug = true;
|
|
|
|
|
....
|
|
|
|
|
|
|
|
|
|
Since the NextProtoNego class is in the boot classpath, we chose not to
|
|
|
|
|
use logging libraries because we do not want to override application
|
|
|
|
|
logging library choices; therefore the logging is performed directly on
|
|
|
|
|
`System.err.`
|
|
|
|
|
|
|
|
|
|
[[npn-license-details]]
|
|
|
|
|
== License Details
|
|
|
|
|
|
|
|
|
|
The NPN implementation relies on modification of a few OpenJDK classes
|
|
|
|
|
and on a few new classes that need to live in the `sun.security.ssl`
|
|
|
|
|
package. These classes are released under the same GPLv2+exception
|
|
|
|
|
license of OpenJDK.
|
|
|
|
|
|
|
|
|
|
The NextProtoNego class is released under same license as the classes of
|
|
|
|
|
the Jetty project.
|
|
|
|
|
|
|
|
|
|
[[npn-versions]]
|
|
|
|
|
== Versions
|
|
|
|
|
|
|
|
|
|
The NPN implementation, relying on modifications of OpenJDK classes,
|
|
|
|
|
updates every time there are updates to the modified OpenJDK classes.
|
|
|
|
|
|
|
|
|
|
.NPN vs. OpenJDK versions
|
|
|
|
|
[cols=",",options="header",]
|
|
|
|
|
|==========================================================
|
|
|
|
|
|NPN version |OpenJDK version
|
|
|
|
|
|1.0.0.v20120402 |1.7.0 - 1.7.0u2 - 1.7.0u3
|
|
|
|
|
|1.1.0.v20120525 |1.7.0u4 - 1.7.0u5
|
|
|
|
|
|1.1.1.v20121030 |1.7.0u6 - 1.7.0u7
|
|
|
|
|
|1.1.3.v20130313 |1.7.0u9 - 1.7.0u10 - 1.7.0u11
|
|
|
|
|
|1.1.4.v20130313 |1.7.0u13
|
|
|
|
|
|1.1.5.v20130313 |1.7.0u15 - 1.7.0u17 - 1.7.0u21 - 1.7.0u25
|
|
|
|
|
|1.1.6.v20130911 |1.7.0u40 - 1.7.0u45 - 1.7.0u51
|
|
|
|
|
|1.1.8.v20141013 |1.7.0u55 - 1.7.0u60 - 1.7.0u65 - 1.7.0u67
|
|
|
|
|
|1.1.9.v20141016 |1.7.0u71 - 1.7.0u72
|
|
|
|
|
|1.1.10.v20150130 |1.7.0u75 - 1.7.0u76 - 1.7.0u79
|
|
|
|
|
|1.1.11.v20150415 |1.7.0u80
|
|
|
|
|
|==========================================================
|
|
|
|
|
|
|
|
|
|
[[npn-build]]
|
|
|
|
|
== How to build NPN
|
|
|
|
|
|
|
|
|
|
This section is for Jetty developers that need to update the NPN
|
|
|
|
|
implementation with the OpenJDK versions.
|
|
|
|
|
|
|
|
|
|
Clone the OpenJDK repository with the following command:
|
|
|
|
|
|
|
|
|
|
[source, screen, subs="{sub-order}"]
|
|
|
|
|
....
|
|
|
|
|
$ hg clone http://hg.openjdk.java.net/jdk7u/jdk7u jdk7u
|
|
|
|
|
$ cd jdk7u
|
|
|
|
|
$ ./get_source.sh
|
|
|
|
|
|
|
|
|
|
....
|
|
|
|
|
|
|
|
|
|
To update the source to a specific tag, use the following command:
|
|
|
|
|
|
|
|
|
|
[source, screen, subs="{sub-order}"]
|
|
|
|
|
....
|
|
|
|
|
$ ./make/scripts/hgforest.sh update <tag-name>
|
|
|
|
|
|
|
|
|
|
....
|
|
|
|
|
|
|
|
|
|
The list of OpenJDK tags can be obtained from
|
|
|
|
|
http://hg.openjdk.java.net/jdk7u/jdk7u/tags[this page].
|
|
|
|
|
|
|
|
|
|
Then you need to compare and incorporate the OpenJDK source changes into
|
|
|
|
|
the modified OpenJDK classes at the
|
|
|
|
|
https://github.com/jetty-project/jetty-npn[NPN GitHub Repository].
|
WalkerWatch