public class TLS
extends java.lang.Object
The underlying SSLEngine has four ports: plaintext input/output and
ciphertext input/output. These are modeled as a BidiShape
element for use in stream topologies, where the plaintext ports are on the
left hand side of the shape and the ciphertext ports on the right hand side.
Configuring JSSE is a rather complex topic, please refer to the JDK platform
documentation or the excellent user guide that is part of the Play Framework
documentation. The philosophy of this integration into Akka Streams is to
expose all knobs and dials to client code and therefore not limit the
configuration possibilities. In particular the client code will have to
provide the SSLContext from which the SSLEngine is then created. Handshake
parameters are set using NegotiateNewSession
messages, the settings for
the initial handshake need to be provided up front using the same class;
please refer to the method documentation below.
'''IMPORTANT NOTE'''
The TLS specification does not permit half-closing of the user data session
that it transports—to be precise a half-close will always promptly lead to a
full close. This means that canceling the plaintext output or completing the
plaintext input of the SslTls stage will lead to full termination of the
secure connection without regard to whether bytes are remaining to be sent or
received, respectively. Especially for a client the common idiom of attaching
a finite Source to the plaintext input and transforming the plaintext response
bytes coming out will not work out of the box due to early termination of the
connection. For this reason there is a parameter that determines whether the
SslTls stage shall ignore completion and/or cancellation events, and the
default is to ignore completion (in view of the client–server scenario). In
order to terminate the connection the client will then need to cancel the
plaintext output as soon as all expected bytes have been received. When
ignoring both types of events the stage will shut down once both events have
been received. See also TLSClosing
.
Constructor and Description |
---|
TLS() |
Modifier and Type | Method and Description |
---|---|
static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> |
apply(scala.Function0<javax.net.ssl.SSLEngine> createSSLEngine,
scala.Function1<javax.net.ssl.SSLSession,scala.util.Try<scala.runtime.BoxedUnit>> verifySession,
TLSClosing closing)
Create a StreamTls
BidiFlow . |
static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> |
apply(scala.Function0<javax.net.ssl.SSLEngine> createSSLEngine,
TLSClosing closing)
Create a StreamTls
BidiFlow . |
static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> |
apply(javax.net.ssl.SSLContext sslContext,
scala.Option<AkkaSSLConfig> sslConfig,
TLSProtocol.NegotiateNewSession firstSession,
TLSRole role,
TLSClosing closing,
scala.Option<scala.Tuple2<java.lang.String,java.lang.Object>> hostInfo)
Create a StreamTls
BidiFlow . |
static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> |
apply(javax.net.ssl.SSLContext sslContext,
TLSProtocol.NegotiateNewSession firstSession,
TLSRole role)
Create a StreamTls
BidiFlow . |
static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> |
apply(javax.net.ssl.SSLContext sslContext,
TLSProtocol.NegotiateNewSession firstSession,
TLSRole role,
TLSClosing closing,
scala.Option<scala.Tuple2<java.lang.String,java.lang.Object>> hostInfo)
Create a StreamTls
BidiFlow . |
public static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> apply(javax.net.ssl.SSLContext sslContext, scala.Option<AkkaSSLConfig> sslConfig, TLSProtocol.NegotiateNewSession firstSession, TLSRole role, TLSClosing closing, scala.Option<scala.Tuple2<java.lang.String,java.lang.Object>> hostInfo)
BidiFlow
. The
SSLContext will be used to create an SSLEngine to which then the
firstSession
parameters are applied before initiating the first
handshake. The role
parameter determines the SSLEngine’s role; this is
often the same as the underlying transport’s server or client role, but
that is not a requirement and depends entirely on the application
protocol.
For a description of the closing
parameter please refer to TLSClosing
.
The hostInfo
parameter allows to optionally specify a pair of hostname and port
that will be used when creating the SSLEngine with sslContext.createSslEngine
.
The SSLEngine may use this information e.g. when an endpoint identification algorithm was
configured using javax.net.ssl.SSLParameters.setEndpointIdentificationAlgorithm
.
sslContext
- (undocumented)sslConfig
- (undocumented)firstSession
- (undocumented)role
- (undocumented)closing
- (undocumented)hostInfo
- (undocumented)public static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> apply(javax.net.ssl.SSLContext sslContext, TLSProtocol.NegotiateNewSession firstSession, TLSRole role, TLSClosing closing, scala.Option<scala.Tuple2<java.lang.String,java.lang.Object>> hostInfo)
BidiFlow
. The
SSLContext will be used to create an SSLEngine to which then the
firstSession
parameters are applied before initiating the first
handshake. The role
parameter determines the SSLEngine’s role; this is
often the same as the underlying transport’s server or client role, but
that is not a requirement and depends entirely on the application
protocol.
For a description of the closing
parameter please refer to TLSClosing
.
The hostInfo
parameter allows to optionally specify a pair of hostname and port
that will be used when creating the SSLEngine with sslContext.createSslEngine
.
The SSLEngine may use this information e.g. when an endpoint identification algorithm was
configured using javax.net.ssl.SSLParameters.setEndpointIdentificationAlgorithm
.
sslContext
- (undocumented)firstSession
- (undocumented)role
- (undocumented)closing
- (undocumented)hostInfo
- (undocumented)public static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> apply(javax.net.ssl.SSLContext sslContext, TLSProtocol.NegotiateNewSession firstSession, TLSRole role)
BidiFlow
. The
SSLContext will be used to create an SSLEngine to which then the
firstSession
parameters are applied before initiating the first
handshake. The role
parameter determines the SSLEngine’s role; this is
often the same as the underlying transport’s server or client role, but
that is not a requirement and depends entirely on the application
protocol.sslContext
- (undocumented)firstSession
- (undocumented)role
- (undocumented)public static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> apply(scala.Function0<javax.net.ssl.SSLEngine> createSSLEngine, scala.Function1<javax.net.ssl.SSLSession,scala.util.Try<scala.runtime.BoxedUnit>> verifySession, TLSClosing closing)
BidiFlow
. This is a low-level interface.
You can specify a constructor to create an SSLEngine that must already be configured for client and server mode and with all the parameters for the first session.
You can specify a verification function that will be called after every successful handshake to verify additional session information.
For a description of the closing
parameter please refer to TLSClosing
.
createSSLEngine
- (undocumented)verifySession
- (undocumented)closing
- (undocumented)public static BidiFlow<TLSProtocol.SslTlsOutbound,ByteString,ByteString,TLSProtocol.SslTlsInbound,NotUsed> apply(scala.Function0<javax.net.ssl.SSLEngine> createSSLEngine, TLSClosing closing)
BidiFlow
. This is a low-level interface.
You can specify a constructor to create an SSLEngine that must already be configured for client and server mode and with all the parameters for the first session.
For a description of the closing
parameter please refer to TLSClosing
.
createSSLEngine
- (undocumented)closing
- (undocumented)