Top Description Inners Fields Constructors Methods
io.netty.handler.ssl

public abstract Class SslMasterKeyHandler

extends ChannelInboundHandlerAdapter
Class Inheritance
Known Direct Subclasses
io.netty.handler.ssl.SslMasterKeyHandler.WiresharkSslMasterKeyHandler
Imports
io.netty.buffer.ByteBufUtil, io.netty.channel.ChannelHandlerContext, .ChannelInboundHandlerAdapter, io.netty.util.internal.ReflectionUtil, .SystemPropertyUtil, io.netty.util.internal.logging.InternalLogger, .InternalLoggerFactory, javax.crypto.SecretKey, javax.crypto.spec.SecretKeySpec, javax.net.ssl.SSLEngine, .SSLSession, java.lang.reflect.Field
The SslMasterKeyHandler is a channel-handler you can include in your pipeline to consume the master key & session identifier for a TLS session. This can be very useful, for instance the WiresharkSslMasterKeyHandler implementation will log the secret & identifier in a format that is consumable by Wireshark -- allowing easy decryption of pcap/tcpdumps.

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
SslMasterKeyHandler.WiresharkSslMasterKeyHandler

Record the session identifier and master key to the InternalLogger named io.netty.wireshark.

Field Summary

Modifier and TypeField and Description
private static final InternalLogger
logger

private static final Class<?>
SSL_SESSIONIMPL_CLASS

The JRE SSLSessionImpl cannot be imported

private static final Field
SSL_SESSIONIMPL_MASTER_SECRET_FIELD

The master key field in the SSLSessionImpl

public static final String
SYSTEM_PROP_KEY

A system property that can be used to turn on/off the SslMasterKeyHandler dynamically without having to edit your pipeline.

private static final Throwable
UNAVAILABILITY_CAUSE

The unavailability cause of whether the private Sun implementation of SSLSessionImpl is available.

Constructor Summary

AccessConstructor and Description
protected
SslMasterKeyHandler()

Constructor.

Method Summary

Modifier and TypeMethod and Description
protected abstract void
accept(SecretKey
A 48-byte secret shared between the client and server.
masterKey, SSLSession
The current TLS session
session)

Consume the master key for the session and the sessionId

public static void
ensureSunSslEngineAvailability()

Ensure that SSLSessionImpl is available.

public static boolean
isSunSslEngineAvailable()

protected boolean

Returns:

true if it should handle, false otherwise.
masterKeyHandlerEnabled()

Checks if the handler is set up to actually handle/accept the event.

public static SslMasterKeyHandler
newWireSharkSslMasterKeyHandler()

Create a WiresharkSslMasterKeyHandler instance.

public static Throwable

Returns:

the cause if unavailable. null if available.
sunSslEngineUnavailabilityCause()

Returns the cause of unavailability.

public final void
userEventTriggered(ChannelHandlerContext ctx, Object evt)

Overrides io.netty.channel.ChannelInboundHandlerAdapter.userEventTriggered.

Implements io.netty.channel.ChannelInboundHandler.userEventTriggered.

Calls ChannelHandlerContext#fireUserEventTriggered(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline.
Inherited from io.netty.channel.ChannelInboundHandlerAdapter:
channelActivechannelInactivechannelReadchannelReadCompletechannelRegisteredchannelUnregisteredchannelWritabilityChangedexceptionCaught

Field Detail

loggerback to summary
private static final InternalLogger logger
SSL_SESSIONIMPL_CLASSback to summary
private static final Class<?> SSL_SESSIONIMPL_CLASS

The JRE SSLSessionImpl cannot be imported

SSL_SESSIONIMPL_MASTER_SECRET_FIELDback to summary
private static final Field SSL_SESSIONIMPL_MASTER_SECRET_FIELD

The master key field in the SSLSessionImpl

SYSTEM_PROP_KEYback to summary
public static final String SYSTEM_PROP_KEY

A system property that can be used to turn on/off the SslMasterKeyHandler dynamically without having to edit your pipeline. -Dio.netty.ssl.masterKeyHandler=true

UNAVAILABILITY_CAUSEback to summary
private static final Throwable UNAVAILABILITY_CAUSE

The unavailability cause of whether the private Sun implementation of SSLSessionImpl is available.

Constructor Detail

SslMasterKeyHandlerback to summary
protected SslMasterKeyHandler()

Constructor.

Method Detail

acceptback to summary
protected abstract void accept(SecretKey masterKey, SSLSession session)

Consume the master key for the session and the sessionId

Parameters
masterKey:SecretKey

A 48-byte secret shared between the client and server.

session:SSLSession

The current TLS session

ensureSunSslEngineAvailabilityback to summary
public static void ensureSunSslEngineAvailability()

Ensure that SSLSessionImpl is available.

Exceptions
UnsatisfiedLinkError:
if unavailable
isSunSslEngineAvailableback to summary
public static boolean isSunSslEngineAvailable()
masterKeyHandlerEnabledback to summary
protected boolean masterKeyHandlerEnabled()

Checks if the handler is set up to actually handle/accept the event. By default the SYSTEM_PROP_KEY property is checked, but any implementations of this class are free to override if they have different mechanisms of checking.

Returns:boolean

true if it should handle, false otherwise.

newWireSharkSslMasterKeyHandlerback to summary
public static SslMasterKeyHandler newWireSharkSslMasterKeyHandler()

Create a WiresharkSslMasterKeyHandler instance. This TLS master key handler logs the master key and session-id in a format understood by Wireshark -- this can be especially useful if you need to ever decrypt a TLS session and are using perfect forward secrecy (i.e. Diffie-Hellman) The key and session identifier are forwarded to the log named 'io.netty.wireshark'.

sunSslEngineUnavailabilityCauseback to summary
public static Throwable sunSslEngineUnavailabilityCause()

Returns the cause of unavailability.

Returns:Throwable

the cause if unavailable. null if available.

userEventTriggeredback to summary
public final void userEventTriggered(ChannelHandlerContext ctx, Object evt)

Overrides io.netty.channel.ChannelInboundHandlerAdapter.userEventTriggered.

Implements io.netty.channel.ChannelInboundHandler.userEventTriggered.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.userEventTriggered.

Calls ChannelHandlerContext#fireUserEventTriggered(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Annotations
@Override
io.netty.handler.ssl back to summary

private final Class SslMasterKeyHandler.WiresharkSslMasterKeyHandler

extends SslMasterKeyHandler
Class Inheritance
Record the session identifier and master key to the InternalLogger named io.netty.wireshark. ex. RSA Session-ID:XXX Master-Key:YYY This format is understood by Wireshark 1.6.0. See: Wireshark The key and session identifier are forwarded to the log named 'io.netty.wireshark'.

Field Summary

Modifier and TypeField and Description
private static final InternalLogger
wireshark_logger

Inherited from io.netty.handler.ssl.SslMasterKeyHandler:
SYSTEM_PROP_KEY

Constructor Summary

AccessConstructor and Description
private
WiresharkSslMasterKeyHandler()

Method Summary

Modifier and TypeMethod and Description
protected void
accept(SecretKey
A 48-byte secret shared between the client and server.
masterKey, SSLSession
The current TLS session
session)

Implements abstract io.netty.handler.ssl.SslMasterKeyHandler.accept.

Consume the master key for the session and the sessionId
Inherited from io.netty.handler.ssl.SslMasterKeyHandler:
ensureSunSslEngineAvailabilityisSunSslEngineAvailablemasterKeyHandlerEnablednewWireSharkSslMasterKeyHandlersunSslEngineUnavailabilityCauseuserEventTriggered

Field Detail

wireshark_loggerback to summary
private static final InternalLogger wireshark_logger

Constructor Detail

WiresharkSslMasterKeyHandlerback to summary
private WiresharkSslMasterKeyHandler()

Method Detail

acceptback to summary
protected void accept(SecretKey masterKey, SSLSession session)

Implements abstract io.netty.handler.ssl.SslMasterKeyHandler.accept.

Doc from io.netty.handler.ssl.SslMasterKeyHandler.accept.

Consume the master key for the session and the sessionId

Parameters
masterKey:SecretKey

A 48-byte secret shared between the client and server.

session:SSLSession

The current TLS session

Annotations
@Override