org.bouncycastle.tls.TlsPeer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of bctls-lts8on Show documentation
The Bouncy Castle Java APIs for the TLS, including a JSSE provider. The APIs are designed primarily to be used in conjunction with the BC LTS provider but may also be used with other providers providing cryptographic services.
There is a newer version: 2.73.7
Show newest version
package org.bouncycastle.tls;

import java.io.IOException;

import org.bouncycastle.tls.crypto.TlsCertificate;
import org.bouncycastle.tls.crypto.TlsCrypto;

/**
 * Base interface for a (D)TLS endpoint.
 */
public interface TlsPeer
{
    TlsCrypto getCrypto();

    void notifyCloseHandle(TlsCloseable closehandle);

    void cancel() throws IOException;

    ProtocolVersion[] getProtocolVersions();

    int[] getCipherSuites();

    /**
     * Notifies the peer that a new handshake is about to begin.
     */
    void notifyHandshakeBeginning() throws IOException;

    /**
     * 
     * 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).
     * 
     * 
     * @return the handshake timeout, in milliseconds.
     */
    int getHandshakeTimeoutMillis();

    /**
     * 
     * NOTE: Currently only respected by DTLS protocols.
     * 
     * 
     * Specify the time, in milliseconds, after which a handshake packet is resent.
     * 
     * 
     * @return the handshake resend time, in milliseconds.
     */
    int getHandshakeResendTimeMillis();

    boolean allowLegacyResumption();

    int getMaxCertificateChainLength();

    int getMaxHandshakeMessageSize();

    short[] getPskKeyExchangeModes();

    /**
     * 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.
     */
    boolean requiresCloseNotify();

    /**
     * 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).
     * 
     * @return true if the handshake should be aborted when the peer does not negotiate
     *         the extended_master_secret extension, or false to support legacy
     *         interoperability.
     */
    boolean requiresExtendedMasterSecret();

    /**
     * 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.
     * 
     * @return true if the 'signatureAlgorithm' of received certificates should be
     *         checked, or false to skip those checks.
     *
     * @deprecated No longer called by the protocol classes. Can call
     *             {@link TlsUtils#checkPeerSigAlgs(TlsContext, TlsCertificate[])} once a complete
     *             CertPath has been determined (i.e. as part of chain validation).
     */
    boolean shouldCheckSigAlgOfPeerCerts();

    boolean shouldUseExtendedMasterSecret();

    /**
     * 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.
     * 
     * @return true if random extra padding should be added during block cipher
     *         encryption, or false to always use the minimum amount of required
     *         padding.
     */
    boolean shouldUseExtendedPadding();

    /**
     * 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.
     * 
     * @return 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.
     */
    boolean shouldUseGMTUnixTime();

    /**
     * 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.
     */
    void notifySecureRenegotiation(boolean secureRenegotiation) throws IOException;

    TlsKeyExchangeFactory getKeyExchangeFactory() throws IOException;

    /**
     * This method will be called when an alert is raised by the protocol.
     *
     * @param alertLevel       {@link AlertLevel}
     * @param alertDescription {@link AlertDescription}
     * @param message          A human-readable message explaining what caused this alert. May be null.
     * @param cause            The {@link Throwable} that caused this alert to be raised. May be null.
     */
    void notifyAlertRaised(short alertLevel, short alertDescription, String message, Throwable cause);

    /**
     * This method will be called when an alert is received from the remote peer.
     *
     * @param alertLevel       {@link AlertLevel}
     * @param alertDescription {@link AlertDescription}
     */
    void notifyAlertReceived(short alertLevel, short alertDescription);

    /**
     * Notifies the peer that the connection has been closed.
     */
    void notifyConnectionClosed();

    /**
     * Notifies the peer that the handshake has been successfully completed.
     */
    void notifyHandshakeComplete() throws IOException;

    /**
     * Return a {@link 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.
     * 
     * @return an instance of {@link TlsHeartbeat}.
     * @see DefaultTlsHeartbeat
     */
    TlsHeartbeat getHeartbeat();

    /**
     * 
     * Return the heartbeat mode applicable to the remote peer. Heartbeats are described in RFC
     * 6520.
     * 
     * 
     * See enumeration class {@link HeartbeatMode} for appropriate return values.
     * 
     * 
     * @return the {@link HeartbeatMode} value.
     */
    short getHeartbeatPolicy();

    /**
     * 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.
     * 
     * @return The {@link RenegotiationPolicy} constant corresponding to the desired policy.
     * @see RenegotiationPolicy
     */
    int getRenegotiationPolicy();
}