Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Jetty/Feature/NPN"
Line 26: | Line 26: | ||
The API is composed by a single class, <code>org.eclipse.jetty.npn.NextProtoNego</code>, and applications need to register instances of <code>SSLSocket</code> or <code>SSLEngine</code> with a client or server provider (depending on whether the application is a client or server application). | The API is composed by a single class, <code>org.eclipse.jetty.npn.NextProtoNego</code>, and applications need to register instances of <code>SSLSocket</code> or <code>SSLEngine</code> with a client or server provider (depending on whether the application is a client or server application). | ||
+ | Refer to [<code>NextProtoNego</code> javadocs http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/npn/NextProtoNego.html] and to the examples below for further details about client and server provider methods. | ||
===Client Example=== | ===Client Example=== | ||
+ | |||
<source lang="java"> | <source lang="java"> | ||
+ | SSLContext sslContext = ...; | ||
+ | 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() | ||
+ | { | ||
+ | } | ||
+ | |||
+ | @Override | ||
+ | public String selectProtocol(List<String> protocols) | ||
+ | { | ||
+ | return protocols.get(0); | ||
+ | } | ||
+ | }); | ||
</source> | </source> | ||
+ | Methods <code>supports()</code>, <code>unsupported()</code> and <code>selectProtocol(List<String>)</code> will be called by the NPN implementation, so that the application can, respectively, decide whether to support NPN, whether the server supports NPN, and select one of the protocols supported by the server. | ||
+ | |||
+ | The example for <code>SSLEngine</code> is identical, and you just need to replace the <code>SSLSocket</code> instance with a <code>SSLEngine</code> instance. | ||
+ | |||
+ | ===Server Example=== | ||
==Implementation Details== | ==Implementation Details== |
Revision as of 05:55, 12 March 2012
Contents
Introduction
The Jetty project provides an implementation of the Next Protocol Negotiation TLS Extension (NPN) for OpenJDK 7 or greater.
Jetty's NPN implementation, although hosted under the umbrella of the Jetty project, is independent of Jetty (the Servlet Container), and can be reused in any other Java network server.
Feature
JVM Startup Usage
In order to enable NPN support, you need to start the JVM with:
java -Xbootclasspath/p:<path_to_npn_boot_jar> ...
where path_to_npn_boot_jar
is the path on file system for the NPN Boot jar file, for example one at the following Maven coordinates org.mortbay.jetty.npn:npn-boot.
API Usage
Applications needs to interact with the negotiation of the next protocol performed by the NPN TLS extension. For example, server applications need to know whether the client supports NPN, and client applications needs to know the list of protocols supported by the server, and so on.
In order to provide this interaction, Jetty's NPN implementation provides an API to applications, hosted at Maven coordinates org.eclipse.jetty.npn:npn-api
.
This dependency needs to be declared as "provided", because it is already included in the npn-boot
jar (see section above) and therefore will be available in the boot classpath.
The API is composed by a single class, org.eclipse.jetty.npn.NextProtoNego
, and applications need to register instances of SSLSocket
or SSLEngine
with a client or server provider (depending on whether the application is a client or server application).
Refer to [NextProtoNego
javadocs http://download.eclipse.org/jetty/stable-7/apidocs/org/eclipse/jetty/npn/NextProtoNego.html] and to the examples below for further details about client and server provider methods.
Client Example
SSLContext sslContext = ...; 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() { } @Override public String selectProtocol(List<String> protocols) { return protocols.get(0); } });
Methods supports()
, unsupported()
and selectProtocol(List<String>)
will be called by the NPN implementation, so that the application can, respectively, decide whether to support NPN, whether the server supports NPN, and select one of the protocols supported by the server.
The example for SSLEngine
is identical, and you just need to replace the SSLSocket
instance with a SSLEngine
instance.