Package org.bouncycastle.tls

Interface TlsServer

All Superinterfaces:

TlsPeer

All Known Implementing Classes:

AbstractTlsServer, DefaultTlsServer, PSKTlsServer, SRPTlsServer

public interface TlsServer
extends TlsPeer

Interface describing a TLS server endpoint.

Method Summary

Modifier and Type	Method	Description
CertificateRequest	getCertificateRequest()
CertificateStatus	getCertificateStatus()	This method will be called (only) if SecurityParameters.getStatusRequestVersion() is non-zero, meaning the client asked for a stapled response and the server undertook to answer: up to (D)TLS 1.2, that it echoed an extension of type "status_request" (RFC 6066 sec. 8.
TlsCredentials	getCredentials()	Return server credentials to use.
TlsDHConfig	getDHConfig()
TlsECConfig	getECDHConfig()
TlsPSKExternal	getExternalPSK(java.util.Vector identities)	WARNING: EXPERIMENTAL FEATURE, UNSTABLE API Return the external PSK to select from the ClientHello.
byte[]	getNewSessionID()
NewSessionTicket	getNewSessionTicket()	RFC 5077 3.3.
TlsPSKIdentityManager	getPSKIdentityManager()
int	getSelectedCipherSuite()
java.util.Hashtable	getServerExtensions()
void	getServerExtensionsForConnection(java.util.Hashtable serverExtensions)
java.util.Vector	getServerSupplementalData()
ProtocolVersion	getServerVersion()
TlsSession	getSessionToResume(byte[] sessionID)	Return the specified session, if available.
TlsSRPLoginParameters	getSRPLoginParameters()
int[]	getSupportedGroups()
void	init(TlsServerContext context)
void	notifyClientCertificate(Certificate clientCertificate)	Called by the protocol handler to report the client certificate, only if getCertificateRequest() returned non-null.
void	notifyClientVersion(ProtocolVersion clientVersion)
void	notifyFallback(boolean isFallback)
void	notifyOfferedCipherSuites(int[] offeredCipherSuites)
void	notifySession(TlsSession session)
boolean	preferLocalSupportedGroups()
void	processClientExtensions(java.util.Hashtable clientExtensions)
void	processClientSupplementalData(java.util.Vector clientSupplementalData)

Methods inherited from interface org.bouncycastle.tls.TlsPeer

allowLegacyResumption, cancel, getCipherSuites, getCrypto, getHandshakeResendTimeMillis, getHandshakeTimeoutMillis, getHeartbeat, getHeartbeatPolicy, getKeyExchangeFactory, getMaxCertificateChainLength, getMaxHandshakeMessageSize, getProtocolVersions, getPskKeyExchangeModes, getRenegotiationPolicy, notifyAlertRaised, notifyAlertReceived, notifyCloseHandle, notifyConnectionClosed, notifyHandshakeBeginning, notifyHandshakeComplete, notifySecureRenegotiation, requiresCloseNotify, requiresExtendedMasterSecret, shouldCheckSigAlgOfPeerCerts, shouldUseExtendedMasterSecret, shouldUseExtendedPadding, shouldUseGMTUnixTime

Method Detail

preferLocalSupportedGroups

boolean preferLocalSupportedGroups()

init

void init(TlsServerContext context)

getSessionToResume

TlsSession getSessionToResume(byte[] sessionID)

Return the specified session, if available. Note that the peer's certificate chain for the session (if any) may need to be periodically revalidated.

Parameters:

sessionID - the ID of the session to resume.

Returns:

A TlsSession with the specified session ID, or null.

See Also:

SessionParameters.getPeerCertificate()

getNewSessionID

byte[] getNewSessionID()

getExternalPSK

TlsPSKExternal getExternalPSK(java.util.Vector identities)
                       throws java.io.IOException

WARNING: EXPERIMENTAL FEATURE, UNSTABLE API Return the external PSK to select from the ClientHello. Note that this will only be called when TLS 1.3 or higher is amongst the offered protocol versions, and one or more PSKs are actually offered.

Parameters:

identities - a Vector of PskIdentity instances.

Returns:

the TlsPSKExternal corresponding to the selected identity, or null to not select any.

Throws:

java.io.IOException - if the handshake should be aborted. An implementation may throw a TlsFatalAlert to control the alert sent to the peer - e.g. AlertDescription.unknown_psk_identity when none of the offered identities is recognised, or AlertDescription.decrypt_error when an identity is recognised but is invalid or expired (see RFC 8446 6.2). Returning null instead leaves PSK unselected without aborting.

notifySession

void notifySession(TlsSession session)

notifyClientVersion

void notifyClientVersion(ProtocolVersion clientVersion)
                  throws java.io.IOException

Throws:

java.io.IOException

notifyFallback

void notifyFallback(boolean isFallback)
             throws java.io.IOException

Throws:

java.io.IOException

notifyOfferedCipherSuites

void notifyOfferedCipherSuites(int[] offeredCipherSuites)
                        throws java.io.IOException

Throws:

java.io.IOException

processClientExtensions

void processClientExtensions(java.util.Hashtable clientExtensions)
                      throws java.io.IOException

Throws:

java.io.IOException

getServerVersion

ProtocolVersion getServerVersion()
                          throws java.io.IOException

Throws:

java.io.IOException

getSupportedGroups

int[] getSupportedGroups()
                  throws java.io.IOException

Throws:

java.io.IOException

getSelectedCipherSuite

int getSelectedCipherSuite()
                    throws java.io.IOException

Throws:

java.io.IOException

getServerExtensions

java.util.Hashtable getServerExtensions()
                                 throws java.io.IOException

Throws:

java.io.IOException

getServerExtensionsForConnection

void getServerExtensionsForConnection(java.util.Hashtable serverExtensions)
                               throws java.io.IOException

Throws:

java.io.IOException

getServerSupplementalData

java.util.Vector getServerSupplementalData()
                                    throws java.io.IOException

Throws:

java.io.IOException

getCredentials

TlsCredentials getCredentials()
                       throws java.io.IOException

Return server credentials to use. The returned value may be null, or else it MUST implement exactly one of TlsCredentialedAgreement, TlsCredentialedDecryptor, or TlsCredentialedSigner, depending on the key exchange that was negotiated.

Returns:

a TlsCredentials object or null for anonymous key exchanges

Throws:

java.io.IOException

getCertificateStatus

CertificateStatus getCertificateStatus()
                                throws java.io.IOException

This method will be called (only) if SecurityParameters.getStatusRequestVersion() is non-zero, meaning the client asked for a stapled response and the server undertook to answer: up to (D)TLS 1.2, that it echoed an extension of type "status_request" (RFC 6066 sec. 8. Certificate Status Request) or "status_request_v2" (RFC 6961 sec. 2.2. Multiple Certificate Status Request Record) with empty "extension_data" in the extended server hello; in TLS 1.3, simply that the client offered "status_request".

The status request version says which of the two shapes the client will accept; returning the other one is a fatal alert at the client:

• 1 – "status_request". Return a CertificateStatusType.ocsp status carrying a single response, for the end-entity certificate.
• 2 – "status_request_v2" was echoed. Return a CertificateStatusType.ocsp_multi status carrying one entry per certificate in the chain that was sent, in the same order, with a null entry wherever no response is available.

Whether either extension is echoed at all up to (D)TLS 1.2 is decided by AbstractTlsServer.allowCertificateStatus() (defaults to true) and AbstractTlsServer.allowMultiCertStatus() (defaults to false).

How the returned status reaches the client depends on the negotiated version. Up to (D)TLS 1.2 it is sent as a handshake message of type "certificate_status", for the whole chain at once. In TLS 1.3 there is no such message: the response travels in a "status_request" extension of the CertificateEntry containing the certificate it answers for (RFC 8446 sec. 4.4.2.1), and the protocol distributes what this callback returns across those entries - an CertificateStatusType.ocsp status answering for the end-entity certificate, an CertificateStatusType.ocsp_multi status answering positionally, entry i of its list for certificate i of the chain. So a TLS 1.3 server with a response for more than the end-entity certificate returns the ocsp_multi shape even though the status request version is 1. An entry the server has itself given a "status_request" extension - by attaching it to the Certificate its credentials supply, which was previously the only way to staple in TLS 1.3 - is left as it stands.

OCSPStaplingServerExample in the misc module is a worked example.

Returns:

A CertificateStatus to be sent to the client (or null for none).

Throws:

java.io.IOException

getCertificateRequest

CertificateRequest getCertificateRequest()
                                  throws java.io.IOException

Throws:

java.io.IOException

getPSKIdentityManager

TlsPSKIdentityManager getPSKIdentityManager()
                                     throws java.io.IOException

Throws:

java.io.IOException

getSRPLoginParameters

TlsSRPLoginParameters getSRPLoginParameters()
                                     throws java.io.IOException

Throws:

java.io.IOException

getDHConfig

TlsDHConfig getDHConfig()
                 throws java.io.IOException

Throws:

java.io.IOException

getECDHConfig

TlsECConfig getECDHConfig()
                   throws java.io.IOException

Throws:

java.io.IOException

processClientSupplementalData

void processClientSupplementalData(java.util.Vector clientSupplementalData)
                            throws java.io.IOException

Throws:

java.io.IOException

notifyClientCertificate

void notifyClientCertificate(Certificate clientCertificate)
                      throws java.io.IOException

Called by the protocol handler to report the client certificate, only if getCertificateRequest() returned non-null. Note: this method is responsible for certificate verification and validation.

Parameters:

clientCertificate - the effective client certificate (may be an empty chain).

Throws:

java.io.IOException

getNewSessionTicket

NewSessionTicket getNewSessionTicket()
                              throws java.io.IOException

RFC 5077 3.3. NewSessionTicket Handshake Message.

This method will be called (only) if a NewSessionTicket extension was sent by the server. See RFC 5077 4. Recommended Ticket Construction for recommended format and protection.

Returns:

The ticket.

Throws:

java.io.IOException