Interface PreSharedKeySelector

All Known Implementing Classes:
OpenSSLPreSharedKeySelector
public interface PreSharedKeySelector
The interface for the Tomcat code that responds to the callback from the OpenSSL layer in Tomcat Native to allow Tomcat to select a pre-shared key. It supports server-side TLSv1.2 SSL_CTX_set_psk_server_callback, server-side TLSv1.3 SSL_CTX_set_psk_find_session_callback, client-side TLSv1.2 SSL_CTX_set_psk_client_callback and client-side TLSv1.3 SSL_CTX_set_psk_use_session_callback call-backs.

  • Method Summary

    Modifier and Type
    Method
    Description
    byte[]
    select(long ssl, byte[] identity, int[] cipherSuite)
    Selects the TLSv1.3 pre-shared key and digest on the server side given the provided client identity.
    byte[]
    select(long ssl, String identity)
    Selects the TLSv1.2 pre-shared key on the server side given the provided client identity.
    byte[]
    selectClient(long ssl, String[] identity)
    Selects the TLSv1.2 identity and pre-shared key that the client will present to a server.
    byte[]
    selectClient(long ssl, String[] identity, int[] cipherSuite)
    Selects the TLSv1.3 identity, pre-shared key and digest that the client will present to a server.

  • Method Details

    • select

      byte[] select(long ssl, String identity)
      Selects the TLSv1.2 pre-shared key on the server side given the provided client identity.
      Parameters:
      ssl - the SSL instance
      identity - the PSK identity provided by the client
      Returns:
      the pre-shared key, or null if the identity is not recognized. OpenSSL limits the key to between 1 and 512 bytes long (inclusive). If the byte sequence is truly random then 16 bytes are recommended for 128-bit ciphers and 32 bytes for 256-bit ciphers.

    • select

      byte[] select(long ssl, byte[] identity, int[] cipherSuite)
      Selects the TLSv1.3 pre-shared key and digest on the server side given the provided client identity.

      The callback is a little more complex for TLSv1.3. The return value is still the pre-shared key but OpenSSL also needs to know which digest to use. Because the OpenSSL API only exposes a cipher for this, that is what Tomcat populates the cipherSuite array with but only the digest is relevant.

      Parameters:
      ssl - the SSL instance
      identity - the PSK identity provided by the client
      cipherSuite - a single-element array that must be populated with a IANA TLSv1.3 cipher suite identifier
      Returns:
      the pre-shared key (strictly the input to the KDF), or null if the identity is not recognized. OpenSSL limits the key to between 1 and 48 bytes long (inclusive). If the byte sequence is truly random then 16 bytes are recommended for 128-bit ciphers and 32 bytes for 256-bit ciphers.

    • selectClient

      byte[] selectClient(long ssl, String[] identity)
      Selects the TLSv1.2 identity and pre-shared key that the client will present to a server.
      Parameters:
      ssl - the SSL instance
      identity - a single-element array that must be populated with the PSK identity
      Returns:
      the pre-shared key, or null if no key is available

    • selectClient

      byte[] selectClient(long ssl, String[] identity, int[] cipherSuite)
      Selects the TLSv1.3 identity, pre-shared key and digest that the client will present to a server.
      Parameters:
      ssl - the SSL instance
      identity - a single-element array that must be populated with the PSK identity
      cipherSuite - a single-element array that must be populated with a IANA TLSv1.3 cipher suite identifier
      Returns:
      the pre-shared key (strictly the input to the KDF), or null if no key is available