org.bouncycastle.tls

Interface TlsPeer

All Known Subinterfaces:

TlsClient, TlsServer

All Known Implementing Classes:

AbstractTlsClient, AbstractTlsPeer, AbstractTlsServer, DefaultTlsClient, DefaultTlsServer, PSKTlsClient, PSKTlsServer, SRPTlsClient, SRPTlsServer

public interface TlsPeer

Base interface for a (D)TLS endpoint.

Method Summary

Modifier and Type	Method and Description
boolean	allowLegacyResumption()
void	cancel()
int[]	getCipherSuites()
TlsCrypto	getCrypto()
int	getHandshakeResendTimeMillis() NOTE: Currently only respected by DTLS protocols.
int	getHandshakeTimeoutMillis() NOTE: Currently only respected by DTLS protocols.
TlsHeartbeat	getHeartbeat() Return a TlsHeartbeat instance that will control the generation of heartbeats locally (if permitted by the remote peer), or null to not generate heartbeats.
short	getHeartbeatPolicy() Return the heartbeat mode applicable to the remote peer.
TlsKeyExchangeFactory	getKeyExchangeFactory()
int	getMaxCertificateChainLength()
int	getMaxHandshakeMessageSize()
ProtocolVersion[]	getProtocolVersions()
short[]	getPskKeyExchangeModes()
int	getRenegotiationPolicy() WARNING: EXPERIMENTAL FEATURE Return this peer's policy on renegotiation requests from the remote peer.
void	notifyAlertRaised(short alertLevel, short alertDescription, java.lang.String message, java.lang.Throwable cause) This method will be called when an alert is raised by the protocol.
void	notifyAlertReceived(short alertLevel, short alertDescription) This method will be called when an alert is received from the remote peer.
void	notifyCloseHandle(TlsCloseable closehandle)
void	notifyConnectionClosed() Notifies the peer that the connection has been closed.
void	notifyHandshakeBeginning() Notifies the peer that a new handshake is about to begin.
void	notifyHandshakeComplete() Notifies the peer that the handshake has been successfully completed.
void	notifySecureRenegotiation(boolean secureRenegotiation) RFC 5746 3.4/3.6.
boolean	requiresCloseNotify() This option is provided as a last resort for interoperability with TLS peers that fail to correctly send a close_notify alert at end of stream.
boolean	requiresExtendedMasterSecret() This implementation supports RFC 7627 and will always negotiate the extended_master_secret extension where possible.
boolean	shouldCheckSigAlgOfPeerCerts() Deprecated. No longer called by the protocol classes. Can call TlsUtils.checkPeerSigAlgs(TlsContext, TlsCertificate[]) once a complete CertPath has been determined (i.e. as part of chain validation).
boolean	shouldUseExtendedMasterSecret()
boolean	shouldUseExtendedPadding() See RFC 5246 6.2.3.2.
boolean	shouldUseGMTUnixTime() draft-mathewson-no-gmtunixtime-00 2.

Method Detail

getCrypto

TlsCrypto getCrypto()

notifyCloseHandle

void notifyCloseHandle(TlsCloseable closehandle)

cancel

void cancel()
     throws java.io.IOException

Throws:

java.io.IOException

getProtocolVersions

ProtocolVersion[] getProtocolVersions()

getCipherSuites

int[] getCipherSuites()

notifyHandshakeBeginning

void notifyHandshakeBeginning()
                       throws java.io.IOException

Notifies the peer that a new handshake is about to begin.

Throws:

java.io.IOException

getHandshakeTimeoutMillis

int getHandshakeTimeoutMillis()

NOTE: Currently only respected by DTLS protocols.

Specify the timeout, in milliseconds, to use for the complete handshake process. Negative values are not allowed. A timeout of zero means an infinite timeout (i.e. the handshake will never time out).

Returns:

the handshake timeout, in milliseconds.

getHandshakeResendTimeMillis

int getHandshakeResendTimeMillis()

NOTE: Currently only respected by DTLS protocols.

Specify the time, in milliseconds, after which a handshake packet is resent.

Returns:

the handshake resend time, in milliseconds.

allowLegacyResumption

boolean allowLegacyResumption()

getMaxCertificateChainLength

int getMaxCertificateChainLength()

getMaxHandshakeMessageSize

int getMaxHandshakeMessageSize()

getPskKeyExchangeModes

short[] getPskKeyExchangeModes()

requiresCloseNotify

boolean requiresCloseNotify()

This option is provided as a last resort for interoperability with TLS peers that fail to correctly send a close_notify alert at end of stream. Implementations SHOULD return true; caution is advised if returning false without a full understanding of the implications.

requiresExtendedMasterSecret

boolean requiresExtendedMasterSecret()

This implementation supports RFC 7627 and will always negotiate the extended_master_secret extension where possible. When connecting to a peer that does not offer/accept this extension, it is recommended to abort the handshake. This option is provided for interoperability with legacy peers, although some TLS features will be disabled in that case (see RFC 7627 5.4).

Returns:

true if the handshake should be aborted when the peer does not negotiate the extended_master_secret extension, or false to support legacy interoperability.

shouldCheckSigAlgOfPeerCerts

boolean shouldCheckSigAlgOfPeerCerts()

Deprecated. No longer called by the protocol classes. Can call TlsUtils.checkPeerSigAlgs(TlsContext, TlsCertificate[]) once a complete CertPath has been determined (i.e. as part of chain validation).

Controls whether the protocol will check the 'signatureAlgorithm' of received certificates as specified in RFC 5246 7.4.2, 7.4.4, 7.4.6 and similar rules for earlier TLS versions. We recommend to enable these checks, but this option is provided for cases where the default checks are for some reason too strict.

Returns:

true if the 'signatureAlgorithm' of received certificates should be checked, or false to skip those checks.

shouldUseExtendedMasterSecret

boolean shouldUseExtendedMasterSecret()

shouldUseExtendedPadding

boolean shouldUseExtendedPadding()

See RFC 5246 6.2.3.2. Controls whether block cipher encryption may randomly add extra padding beyond the minimum. Note that in configurations where this is known to be potential security risk this setting will be ignored (and extended padding disabled). Extra padding is always supported when decrypting received records.

Returns:

true if random extra padding should be added during block cipher encryption, or false to always use the minimum amount of required padding.

shouldUseGMTUnixTime

boolean shouldUseGMTUnixTime()

draft-mathewson-no-gmtunixtime-00 2. "If existing users of a TLS implementation may rely on gmt_unix_time containing the current time, we recommend that implementors MAY provide the ability to set gmt_unix_time as an option only, off by default." NOTE: For a server that has negotiated TLS 1.3 (or later), or a client that has offered TLS 1.3 (or later), this is not called and gmt_unix_time is not used.

Returns:

true if the current time should be used in the gmt_unix_time field of Random, or false if gmt_unix_time should contain a cryptographically random value.

notifySecureRenegotiation

void notifySecureRenegotiation(boolean secureRenegotiation)
                        throws java.io.IOException

RFC 5746 3.4/3.6. In case this is false, peers may want to terminate the handshake instead of continuing; see Section 4.1/4.3 for discussion. NOTE: TLS 1.3 forbids renegotiation, so this is never called when TLS 1.3 (or later) was negotiated.

Throws:

java.io.IOException

getKeyExchangeFactory

TlsKeyExchangeFactory getKeyExchangeFactory()
                                     throws java.io.IOException

Throws:

java.io.IOException

notifyAlertRaised

void notifyAlertRaised(short alertLevel,
                       short alertDescription,
                       java.lang.String message,
                       java.lang.Throwable cause)

This method will be called when an alert is raised by the protocol.

Parameters:

alertLevel - AlertLevel

alertDescription - AlertDescription

message - A human-readable message explaining what caused this alert. May be null.

cause - The Throwable that caused this alert to be raised. May be null.

notifyAlertReceived

void notifyAlertReceived(short alertLevel,
                         short alertDescription)

This method will be called when an alert is received from the remote peer.

Parameters:

alertLevel - AlertLevel

alertDescription - AlertDescription

notifyConnectionClosed

void notifyConnectionClosed()

Notifies the peer that the connection has been closed.

notifyHandshakeComplete

void notifyHandshakeComplete()
                      throws java.io.IOException

Notifies the peer that the handshake has been successfully completed.

Throws:

java.io.IOException

getHeartbeat

TlsHeartbeat getHeartbeat()

Return a TlsHeartbeat instance that will control the generation of heartbeats locally (if permitted by the remote peer), or null to not generate heartbeats. Heartbeats are described in RFC 6520.

Returns:

an instance of TlsHeartbeat.

See Also:

DefaultTlsHeartbeat

getHeartbeatPolicy

short getHeartbeatPolicy()

Return the heartbeat mode applicable to the remote peer. Heartbeats are described in RFC 6520.

See enumeration class HeartbeatMode for appropriate return values.

Returns:

the HeartbeatMode value.

getRenegotiationPolicy

int getRenegotiationPolicy()

WARNING: EXPERIMENTAL FEATURE Return this peer's policy on renegotiation requests from the remote peer. This will be called only outside of ongoing handshakes, either when a remote server has sent a hello_request, or a remote client has sent a new ClientHello, and only when the requirements for secure renegotiation (including those of RFC 5746) have been met.

Returns:

The RenegotiationPolicy constant corresponding to the desired policy.

See Also:

RenegotiationPolicy