io.netty.handler.ssl

Interface ResumableX509ExtendedTrustManager

All Superinterfaces:

TrustManager, X509TrustManager

public interface ResumableX509ExtendedTrustManager
extends X509TrustManager

An interface that TrustManager instances can implement, to be notified of resumed SSL sessions.

A TrustManager is called during the TLS handshake, and make decisions about whether the connected peer can be trusted or not. TLS include a feature where previously established sessions can be resumed without going through the trust verification steps.

When an SSLSession is resumed, any values added to it in the prior session may be lost. This interface gives TrustManager implementations an opportunity to restore any values they would normally add during the TLS handshake, before the handshake completion is signalled to the application.

When a session is resumed, the SslHandler will call the relevant resume* method, before completing the handshake promise and sending the SslHandshakeCompletionEvent.SUCCESS event down the pipeline.

A trust manager that does not add values to the handshake session in its check* methods, will typically not have any need to implement this interface.

Note: The implementing trust manager class must extend X509ExtendedTrustManager, otherwise this interface will be ignored by the SslHandler.

Method Summary

Modifier and Type	Method and Description
void	resumeClientTrusted(X509Certificate[] chain, SSLEngine engine) Given the partial or complete certificate chain recovered from the session ticket, and the SSLEngine being used, restore the application state of the associated SSL session.
void	resumeServerTrusted(X509Certificate[] chain, SSLEngine engine) Given the partial or complete certificate chain recovered of the peer, and the SSLEngine being used, restore the application state of the associated SSL session.

Methods inherited from interface javax.net.ssl.X509TrustManager

checkClientTrusted, checkServerTrusted, getAcceptedIssuers

Method Detail

resumeClientTrusted

void resumeClientTrusted(X509Certificate[] chain,
                         SSLEngine engine)
                  throws CertificateException

Given the partial or complete certificate chain recovered from the session ticket, and the SSLEngine being used, restore the application state of the associated SSL session.

This method should obtain the SSLSession from the SSLEngine.getSession() method.

Note: If this method throws CertificateException, the TLS handshake will not necessarily be rejected. The TLS handshake "Finished" message may have already been sent to the peer by the time this method is called.

Implementors should be aware, that peers may make multiple connection attempts using the same session ticket. So this method may be called more than once for the same client, even if prior calls have thrown exceptions or invalidated their sessions.

The given certificate chain is not guaranteed to be the authenticated chain. Implementations that need the authenticated certificate chain will have to re-authenticate the certificates. It is recommended to do so with a PKIXParameters.setDate(Date) set to the session creation date from SSLSession.getCreationTime(). Otherwise, the authentication may fail due to the certificate expiring before the session ticket.

This method is called on the server-side, restoring sessions for clients.

Parameters:

chain - The peer certificate chain.

engine - The begine used for this connection.

Throws:

CertificateException - If the session cannot be restored. Locally, the handshake will appear to have failed, but the peer may have observed a finished handshake.

resumeServerTrusted

void resumeServerTrusted(X509Certificate[] chain,
                         SSLEngine engine)
                  throws CertificateException

Given the partial or complete certificate chain recovered of the peer, and the SSLEngine being used, restore the application state of the associated SSL session.

This method should obtain the SSLSession from the SSLEngine.getSession() method.

Note: If this method throws CertificateException, the TLS handshake will not necessarily be rejected. The TLS handshake "Finished" message may have already been sent to the peer by the time this method is called.

Implementors should be aware, that peers may make multiple connection attempts using the same session ticket. So this method may be called more than once for the same client, even if prior calls have thrown exceptions or invalidated their sessions.

The given certificate chain is not guaranteed to be the authenticated chain. Implementations that need the authenticated certificate chain will have to re-authenticate the certificates. It is recommended to do so with a PKIXParameters.setDate(Date) set to the session creation date from SSLSession.getCreationTime(). Otherwise, the authentication may fail due to the certificate expiring before the session ticket.

This method is called on the client-side, restoring sessions for servers.

Parameters:

chain - The peer certificate chain.

engine - The begine used for this connection.

Throws:

CertificateException - If the session cannot be restored. Locally, the handshake will appear to have failed, but the peer may have observed a finished handshake.