Package io.github.mahmoudimus.quic.tls

Class TlsConfig.Builder

java.lang.Object
io.github.mahmoudimus.quic.tls.TlsConfig.Builder
Enclosing class:
TlsConfig
public static final class TlsConfig.Builder extends Object
Builds a TlsConfig. Builders are not thread-safe.

  • Method Details

    • cipherSuites

      public TlsConfig.Builder cipherSuites(CipherSuite... suites)
      The cipher suites to offer (client) or accept (server), most preferred first. A server picks the first of its suites the client offers.
      Parameters:
      suites - one or more suites
      Returns:
      this builder

    • groups

      public TlsConfig.Builder groups(NamedGroup... groups)
      The key exchange groups, most preferred first. A client sends a key share for the first and lists them all in supported_groups; a server takes the first of its groups the client sent a key share for, or else asks for the first of its groups the client supports with a HelloRetryRequest.
      Parameters:
      groups - one or more groups
      Returns:
      this builder

    • signatureSchemes

      public TlsConfig.Builder signatureSchemes(SignatureScheme... schemes)
      The signature schemes allowed for CertificateVerify, most preferred first. The rsa_pkcs1 schemes cannot be used here; a client always advertises them as well, for the signatures in certificate chains.
      Parameters:
      schemes - one or more schemes
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if a scheme cannot sign a TLS 1.3 CertificateVerify

    • secureRandom

      public TlsConfig.Builder secureRandom(SecureRandom random)
      The source of randomness for hello randoms, key shares and signatures.
      Parameters:
      random - the random source
      Returns:
      this builder

    • maxHandshakeMessageSize

      public TlsConfig.Builder maxHandshakeMessageSize(int bytes)
      The largest handshake message body accepted from the peer; a longer one fails with CRYPTO_BUFFER_EXCEEDED. This bounds what a session buffers per encryption level.
      Parameters:
      bytes - the limit, at least 4096 (RFC 9001 section 4.1.3)
      Returns:
      this builder

    • alpnProtocols

      public TlsConfig.Builder alpnProtocols(String... protocols)
      The application protocols (ALPN). A client offers them in this order; a server without an ALPN selector picks the first of them the client offered. QUIC requires ALPN, so a handshake without a common protocol fails with no_application_protocol. Characters map one to one onto bytes (ISO-8859-1).
      Parameters:
      protocols - the protocol names, such as "h3"
      Returns:
      this builder

    • serverName

      public TlsConfig.Builder serverName(String serverName)
      Client: the server's host name or IP address. A host name is sent as SNI; either is what the server's certificate is checked against.
      Parameters:
      serverName - the host name or IP literal
      Returns:
      this builder

    • trustManager

      public TlsConfig.Builder trustManager(X509TrustManager trustManager)
      Client: the trust manager that validates the server's chain. The default is the JDK's default trust manager.
      Parameters:
      trustManager - the trust manager
      Returns:
      this builder

    • trustAllCertificates

      public TlsConfig.Builder trustAllCertificates(boolean trustAll)
      Client: accept any server certificate without validating its chain or name. The CertificateVerify signature is still checked. For tests only.
      Parameters:
      trustAll - true to skip certificate validation
      Returns:
      this builder

    • verifyHostname

      public TlsConfig.Builder verifyHostname(boolean verify)
      Client: whether the server's certificate must be valid for the server name, as HTTPS endpoint identification checks. On by default.
      Parameters:
      verify - false to skip the host name check
      Returns:
      this builder

    • clientCertificate

      public TlsConfig.Builder clientCertificate(CertifiedKey key)
      Client: the certificate to present if the server asks for one. Without one, the client answers a CertificateRequest with an empty Certificate.
      Parameters:
      key - the chain and key
      Returns:
      this builder

    • certificate

      public TlsConfig.Builder certificate(CertifiedKey key)
      Server: one certificate for every connection.
      Parameters:
      key - the chain and key
      Returns:
      this builder

    • certificate

      public TlsConfig.Builder certificate(List<X509Certificate> chain, PrivateKey privateKey)
      Server: one certificate for every connection.
      Parameters:
      chain - the certificates, end-entity first
      privateKey - the end-entity certificate's private key
      Returns:
      this builder

    • certificateSelector

      public TlsConfig.Builder certificateSelector(Function<ClientHelloInfo,CertifiedKey> selector)
      Server: picks the certificate for each ClientHello, typically by its server name. It runs on the thread that feeds the session its handshake data. Returning null fails the handshake with unrecognized_name if the client sent a name, handshake_failure otherwise.
      Parameters:
      selector - the selector
      Returns:
      this builder

    • alpnSelector

      public TlsConfig.Builder alpnSelector(Function<ClientHelloInfo,String> selector)
      Server: picks the application protocol from the client's offer, instead of the preference list. Returning null, or a protocol the client did not offer, fails the handshake with no_application_protocol.
      Parameters:
      selector - the selector
      Returns:
      this builder

    • clientAuth

      public TlsConfig.Builder clientAuth(ClientAuth clientAuth)
      Server: whether to ask the client for a certificate.
      Parameters:
      clientAuth - the policy
      Returns:
      this builder

    • clientTrustManager

      public TlsConfig.Builder clientTrustManager(X509TrustManager trustManager)
      Server: the trust manager that validates client certificates. The default is the JDK's default trust manager.
      Parameters:
      trustManager - the trust manager
      Returns:
      this builder

    • clock

      public TlsConfig.Builder clock(InstantSource clock)
      The wall clock ticket ages and lifetimes are measured with.
      Parameters:
      clock - the clock
      Returns:
      this builder

    • earlyData

      public TlsConfig.Builder earlyData(boolean enabled)
      Turns 0-RTT on or off (off by default). A client then offers early data when its ticket allows it; a server issues tickets that allow early data and accepts it when the policy does. 0-RTT data can be replayed; see EarlyDataPolicy.
      Parameters:
      enabled - whether to use 0-RTT
      Returns:
      this builder

    • sessionTickets

      public TlsConfig.Builder sessionTickets(Ticketer ticketer)
      Server: the ticketer that seals session tickets, which turns on NewSessionTicket and PSK resumption. Servers that share a ticketer accept each other's tickets. Not used with client authentication.
      Parameters:
      ticketer - the ticketer, or null to issue no tickets (the default)
      Returns:
      this builder

    • ticketsPerConnection

      public TlsConfig.Builder ticketsPerConnection(int count)
      Server: how many tickets to send after each handshake. Clients use each ticket once, so more tickets allow more resumed connections before the next full handshake.
      Parameters:
      count - 0 to 16; 2 by default
      Returns:
      this builder

    • earlyDataPolicy

      public TlsConfig.Builder earlyDataPolicy(EarlyDataPolicy policy)
      Server: decides whether to accept 0-RTT data the protocol allows. The default, with earlyData on, is EarlyDataPolicy.antiReplay(); compose an application veto with it rather than replacing it.
      Parameters:
      policy - the policy
      Returns:
      this builder

    • build

      public TlsConfig build()
      Builds the configuration.
      Returns:
      the immutable configuration