Class SSLContext

java.lang.Object
org.apache.tomcat.jni.SSLContext
public final class SSLContext extends Object
JNI bindings for OpenSSL SSL_CTX operations.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    SSLContext.SNICallBack
    Deprecated.
    Unused.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte[]
    DEFAULT_SESSION_ID_CONTEXT
    Default session ID context value.

  • Constructor Summary

    Constructors
    Constructor
    Description
    SSLContext()
    Default constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    addChainCertificateRaw(long ctx, byte[] cert)
    Add a certificate to the certificate chain.
    static boolean
    addClientCACertificateRaw(long ctx, byte[] cert)
    Add a CA certificate we accept as issuer for peer certs
    static void
    clearOptions(long ctx, int options)
    Clears OpenSSL Options.
    static int
    free(long ctx)
    Free the resources used by the Context
    static String[]
    getCiphers(long ctx)
    Returns all cipher suites that are enabled for negotiation in an SSL handshake.
    static int
    getOptions(long ctx)
    Get OpenSSL Option.
    static long
    getSessionCacheMode(long ctx)
    Get the mode of the current used internal session cache.
    static long
    getSessionCacheSize(long ctx)
    Get the size of the internal session cache. http://www.openssl.org/docs/ssl/SSL_CTX_sess_get_cache_size.html
    static long
    getSessionCacheTimeout(long ctx)
    Get the timeout for the internal session cache in seconds. http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html
    static long
    make(long pool, int protocol, int mode)
    Create a new SSL context.
    static long
    sessionAccept(long ctx)
    Returns the total number of session attempts accepted by the server.
    static long
    sessionAcceptGood(long ctx)
    Returns the number of sessions actually reused on the server side.
    static long
    sessionAcceptRenegotiate(long ctx)
    Returns the number of session renegotiations on the server side.
    static long
    sessionCacheFull(long ctx)
    Returns the number of times the session cache grew to the maximum allowed size and therefore further entries could not be inserted.
    static long
    sessionCbHits(long ctx)
    Returns the number of sessions that were resumed by the callback.
    static long
    sessionConnect(long ctx)
    Returns the total number of session connection attempts by the client.
    static long
    sessionConnectGood(long ctx)
    Returns the number of sessions that were actually reused on the client side.
    static long
    sessionConnectRenegotiate(long ctx)
    Returns the number of session renegotiations on the client side.
    static long
    sessionHits(long ctx)
    Returns the number of sessions that were actually reused (hits).
    static long
    sessionMisses(long ctx)
    Returns the number of sessions that were not found in the cache (misses).
    static long
    sessionNumber(long ctx)
    Returns the total number of sessions currently in the cache.
    static long
    sessionTimeouts(long ctx)
    Returns the number of sessions that have timed out.
    static void
    setAlpnProtos(long ctx, String[] alpnProtos, int selectorFailureBehavior)
    Set application layer protocol for application layer protocol negotiation extension
    static boolean
    setCACertificate(long ctx, String file, String path)
    Set File and Directory of concatenated PEM-encoded CA Certificates for Client Auth
    This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with.
    static boolean
    setCARevocation(long ctx, String file, String path)
    Set File of concatenated PEM-encoded CA CRLs or directory of PEM-encoded CA Certificates for Client Auth
    This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with.
    static boolean
    setCertificate(long ctx, String cert, String key, String password, int idx)
    Set Certificate
    Point setCertificateFile at a PEM encoded certificate.
    static boolean
    setCertificateChainFile(long ctx, String file, boolean skipfirst)
    Set File of PEM-encoded Server CA Certificates
    This directive sets the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate.
    static boolean
    setCertificateRaw(long ctx, byte[] cert, byte[] key, int sslAidxRsa)
    Set CertificateRaw
    Use keystore a certificate and key to fill the BIOP
    static void
    setCertVerifyCallback(long ctx, CertificateVerifier verifier)
    Allow to hook CertificateVerifier into the handshake processing.
    static boolean
    setCipherSuite(long ctx, String cipherList)
    Set the TLSv1.2 and below ciphers available for negotiation the in TLS handshake.
    static boolean
    setCipherSuitesEx(long ctx, String cipherSuites)
    Set the TLSv1.3 cipher suites available for negotiation the in TLS handshake.
    static void
    setOptions(long ctx, int options)
    Set OpenSSL Option.
    static long
    setSessionCacheMode(long ctx, long mode)
    Set the mode of the internal session cache and return the previous used mode.
    static long
    setSessionCacheSize(long ctx, long size)
    Set the size of the internal session cache. http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html
    static long
    setSessionCacheTimeout(long ctx, long timeoutSeconds)
    Set the timeout for the internal session cache in seconds. http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html
    static boolean
    setSessionIdContext(long ctx, byte[] sidCtx)
    Set the context within which session be reused (server side only) http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html
    static void
    setSessionTicketKeys(long ctx, byte[] keys)
    Set TLS session keys.
    static void
    setVerify(long ctx, int level, int depth)
    Set Type of Client Certificate verification and Maximum depth of CA Certificates in Client Certificate verification.
    static long
    sniCallBack(long currentCtx, String sniHostName)
    Deprecated.
    Unused.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_SESSION_ID_CONTEXT

      public static final byte[] DEFAULT_SESSION_ID_CONTEXT
      Default session ID context value.

  • Constructor Details

    • SSLContext

      public SSLContext()
      Default constructor. This class provides only static methods.

  • Method Details

    • make

      public static long make(long pool, int protocol, int mode) throws Exception
      Create a new SSL context.
      Parameters:
      pool - The pool to use.
      protocol - The SSL protocol to use. It can be any combination of the following: 
      SSL.SSL_PROTOCOL_SSLV2
SSL.SSL_PROTOCOL_SSLV3
SSL.SSL_PROTOCOL_TLSV1
SSL.SSL_PROTOCOL_TLSV1_1
SSL.SSL_PROTOCOL_TLSV1_2
SSL.SSL_PROTOCOL_TLSV1_3
SSL.SSL_PROTOCOL_ALL ( == all TLS versions, no SSL)
      mode - SSL mode to use 
      SSL_MODE_CLIENT
SSL_MODE_SERVER
SSL_MODE_COMBINED
      Returns:
      The Java representation of a pointer to the newly created SSL Context
      Throws:
      Exception - If the SSL Context could not be created

    • free

      public static int free(long ctx)
      Free the resources used by the Context
      Parameters:
      ctx - Server or Client context to free.
      Returns:
      APR Status code.

    • setOptions

      public static void setOptions(long ctx, int options)
      Set OpenSSL Option.
      Parameters:
      ctx - Server or Client context to use.
      options - See SSL.SSL_OP_* for option flags.

    • getOptions

      public static int getOptions(long ctx)
      Get OpenSSL Option.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      options See SSL.SSL_OP_* for option flags.

    • clearOptions

      public static void clearOptions(long ctx, int options)
      Clears OpenSSL Options.
      Parameters:
      ctx - Server or Client context to use.
      options - See SSL.SSL_OP_* for option flags.

    • getCiphers

      public static String[] getCiphers(long ctx)
      Returns all cipher suites that are enabled for negotiation in an SSL handshake.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      ciphers

    • setCipherSuite

      public static boolean setCipherSuite(long ctx, String cipherList) throws Exception
      Set the TLSv1.2 and below ciphers available for negotiation the in TLS handshake.

      This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the ciphers the client is permitted to negotiate in the TLS handshake phase.

      Parameters:
      ctx - Server or Client context to use.
      cipherList - An OpenSSL cipher specification.
      Returns:
      true if the operation was successful
      Throws:
      Exception - An error occurred

    • setCipherSuitesEx

      public static boolean setCipherSuitesEx(long ctx, String cipherSuites) throws Exception
      Set the TLSv1.3 cipher suites available for negotiation the in TLS handshake.

      This uses a colon-separated list of TLSv1.3 cipher suite names in preference order.

      Parameters:
      ctx - Server or Client context to use.
      cipherSuites - An OpenSSL cipher suite list.
      Returns:
      true if the operation was successful
      Throws:
      Exception - An error occurred

    • setCARevocation

      public static boolean setCARevocation(long ctx, String file, String path) throws Exception
      Set File of concatenated PEM-encoded CA CRLs or directory of PEM-encoded CA Certificates for Client Auth
      This directive sets the all-in-one file where you can assemble the Certificate Revocation Lists (CRL) of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded CRL files, in order of preference.
      The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.
      Parameters:
      ctx - Server or Client context to use.
      file - File of concatenated PEM-encoded CA CRLs for Client Auth.
      path - Directory of PEM-encoded CA Certificates for Client Auth.
      Returns:
      true if the operation was successful
      Throws:
      Exception - An error occurred

    • setCertificateChainFile

      public static boolean setCertificateChainFile(long ctx, String file, boolean skipfirst)
      Set File of PEM-encoded Server CA Certificates
      This directive sets the optional all-in-one file where you can assemble the certificates of Certification Authorities (CA) which form the certificate chain of the server certificate. This starts with the issuing CA certificate of the server certificate and can range up to the root CA certificate. Such a file is simply the concatenation of the various PEM-encoded CA Certificate files, usually in certificate chain order.
      But be careful: Providing the certificate chain works only if you are using a single (either RSA or DSA) based server certificate. If you are using a coupled RSA+DSA certificate pair, this will work only if actually both certificates use the same certificate chain. Else the browsers will be confused in this situation.
      Parameters:
      ctx - Server or Client context to use.
      file - File of PEM-encoded Server CA Certificates.
      skipfirst - Skip first certificate if chain file is inside certificate file.
      Returns:
      true if the operation was successful

    • setCertificate

      public static boolean setCertificate(long ctx, String cert, String key, String password, int idx) throws Exception
      Set Certificate
      Point setCertificateFile at a PEM encoded certificate. If the certificate is encrypted, then you will be prompted for a pass phrase. Note that a kill -HUP will prompt again. A test certificate can be generated with 'make certificate' under built time. Keep in mind that if you've both a RSA and a DSA certificate you can configure both in parallel (to also allow the use of DSA ciphers, etc.)
      If the key is not combined with the certificate, use key param to point at the key file. Keep in mind that if you've both a RSA and a DSA private key you can configure both in parallel (to also allow the use of DSA ciphers, etc.)
      Parameters:
      ctx - Server or Client context to use.
      cert - Certificate file.
      key - Private Key file to use if not in cert.
      password - Certificate password. If null and certificate is encrypted, password prompt will be displayed.
      idx - Certificate index SSL_AIDX_RSA or SSL_AIDX_DSA.
      Returns:
      true if the operation was successful
      Throws:
      Exception - An error occurred

    • setSessionCacheSize

      public static long setSessionCacheSize(long ctx, long size)
      Set the size of the internal session cache. http://www.openssl.org/docs/ssl/SSL_CTX_sess_set_cache_size.html
      Parameters:
      ctx - Server or Client context to use.
      size - The cache size
      Returns:
      the value set

    • getSessionCacheSize

      public static long getSessionCacheSize(long ctx)
      Get the size of the internal session cache. http://www.openssl.org/docs/ssl/SSL_CTX_sess_get_cache_size.html
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      the size

    • setSessionCacheTimeout

      public static long setSessionCacheTimeout(long ctx, long timeoutSeconds)
      Set the timeout for the internal session cache in seconds. http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html
      Parameters:
      ctx - Server or Client context to use.
      timeoutSeconds - Timeout value
      Returns:
      the value set

    • getSessionCacheTimeout

      public static long getSessionCacheTimeout(long ctx)
      Get the timeout for the internal session cache in seconds. http://www.openssl.org/docs/ssl/SSL_CTX_set_timeout.html
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      the timeout

    • setSessionCacheMode

      public static long setSessionCacheMode(long ctx, long mode)
      Set the mode of the internal session cache and return the previous used mode.
      Parameters:
      ctx - Server or Client context to use.
      mode - The mode to set
      Returns:
      the value set

    • getSessionCacheMode

      public static long getSessionCacheMode(long ctx)
      Get the mode of the current used internal session cache.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      the value set

    • sessionAccept

      public static long sessionAccept(long ctx)
      Returns the total number of session attempts accepted by the server.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of accepted sessions

    • sessionAcceptGood

      public static long sessionAcceptGood(long ctx)
      Returns the number of sessions actually reused on the server side.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of good session accepts

    • sessionAcceptRenegotiate

      public static long sessionAcceptRenegotiate(long ctx)
      Returns the number of session renegotiations on the server side.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session renegotiations accepted

    • sessionCacheFull

      public static long sessionCacheFull(long ctx)
      Returns the number of times the session cache grew to the maximum allowed size and therefore further entries could not be inserted.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of times the session cache was full

    • sessionCbHits

      public static long sessionCbHits(long ctx)
      Returns the number of sessions that were resumed by the callback.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session callback hits

    • sessionConnect

      public static long sessionConnect(long ctx)
      Returns the total number of session connection attempts by the client.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session connects

    • sessionConnectGood

      public static long sessionConnectGood(long ctx)
      Returns the number of sessions that were actually reused on the client side.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of good session connects

    • sessionConnectRenegotiate

      public static long sessionConnectRenegotiate(long ctx)
      Returns the number of session renegotiations on the client side.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session renegotiations connected

    • sessionHits

      public static long sessionHits(long ctx)
      Returns the number of sessions that were actually reused (hits).
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session hits

    • sessionMisses

      public static long sessionMisses(long ctx)
      Returns the number of sessions that were not found in the cache (misses).
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session misses

    • sessionNumber

      public static long sessionNumber(long ctx)
      Returns the total number of sessions currently in the cache.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The total number of sessions

    • sessionTimeouts

      public static long sessionTimeouts(long ctx)
      Returns the number of sessions that have timed out.
      Parameters:
      ctx - Server or Client context to use.
      Returns:
      The number of session timeouts

    • setSessionTicketKeys

      public static void setSessionTicketKeys(long ctx, byte[] keys)
      Set TLS session keys. This allows us to share keys across TFEs.
      Parameters:
      ctx - Server or Client context to use.
      keys - Some session keys

    • setCACertificate

      public static boolean setCACertificate(long ctx, String file, String path) throws Exception
      Set File and Directory of concatenated PEM-encoded CA Certificates for Client Auth
      This directive sets the all-in-one file where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a file is simply the concatenation of the various PEM-encoded Certificate files, in order of preference. This can be used alternatively and/or additionally to path.
      The files in this directory have to be PEM-encoded and are accessed through hash filenames. So usually you can't just place the Certificate files there: you also have to create symbolic links named hash-value.N. And you should always make sure this directory contains the appropriate symbolic links. Use the Makefile which comes with mod_ssl to accomplish this task.
      Parameters:
      ctx - Server or Client context to use.
      file - File of concatenated PEM-encoded CA Certificates for Client Auth.
      path - Directory of PEM-encoded CA Certificates for Client Auth.
      Returns:
      true if the operation was successful
      Throws:
      Exception - An error occurred

    • setVerify

      public static void setVerify(long ctx, int level, int depth)
      Set Type of Client Certificate verification and Maximum depth of CA Certificates in Client Certificate verification.
      This directive sets the Certificate verification level for the Client Authentication. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces an SSL renegotiation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent.
      The following levels are available for level: 
      SSL_CVERIFY_NONE           - No client Certificate is required at all
SSL_CVERIFY_OPTIONAL       - The client may present a valid Certificate
SSL_CVERIFY_REQUIRE        - The client has to present a valid Certificate
SSL_CVERIFY_OPTIONAL_NO_CA - The client may present a valid Certificate
                             but it need not to be (successfully) verifiable

      The depth actually is the maximum number of intermediate certificate issuers, i.e. the number of CA certificates which are max allowed to be followed while verifying the client certificate. A depth of 0 means that self-signed client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e. the CA's certificate is under setCACertificatePath), etc.
      Parameters:
      ctx - Server or Client context to use.
      level - Type of Client Certificate verification.
      depth - Maximum depth of CA Certificates in Client Certificate verification.

    • sniCallBack

      @Deprecated public static long sniCallBack(long currentCtx, String sniHostName)
      Deprecated.
      Unused. This method will be removed in Tomcat 12 onwards.
      When tc-native encounters a SNI extension in the TLS handshake it will call this method to determine which OpenSSL SSLContext to use for the connection.
      Parameters:
      currentCtx - The OpenSSL SSLContext that the handshake started to use. This will be the default OpenSSL SSLContext for the endpoint associated with the socket.
      sniHostName - The host name requested by the client
      Returns:
      The Java representation of the pointer to the OpenSSL SSLContext to use for the given host or zero if no SSLContext could be identified. Always returns 0.

    • setCertVerifyCallback

      public static void setCertVerifyCallback(long ctx, CertificateVerifier verifier)
      Allow to hook CertificateVerifier into the handshake processing. This will call SSL_CTX_set_cert_verify_callback and so replace the default verification callback used by openssl
      Parameters:
      ctx - Server or Client context to use.
      verifier - the verifier to call during handshake.

    • setAlpnProtos

      public static void setAlpnProtos(long ctx, String[] alpnProtos, int selectorFailureBehavior)
      Set application layer protocol for application layer protocol negotiation extension
      Parameters:
      ctx - Server context to use.
      alpnProtos - protocols in priority order
      selectorFailureBehavior - see SSL.SSL_SELECTOR_FAILURE_NO_ADVERTISE and SSL.SSL_SELECTOR_FAILURE_CHOOSE_MY_LAST_PROTOCOL

    • setSessionIdContext

      public static boolean setSessionIdContext(long ctx, byte[] sidCtx)
      Set the context within which session be reused (server side only) http://www.openssl.org/docs/ssl/SSL_CTX_set_session_id_context.html
      Parameters:
      ctx - Server context to use.
      sidCtx - can be any kind of binary data, it is therefore possible to use e.g. the name of the application and/or the hostname and/or service name
      Returns:
      true if success, false otherwise.

    • setCertificateRaw

      public static boolean setCertificateRaw(long ctx, byte[] cert, byte[] key, int sslAidxRsa)
      Set CertificateRaw
      Use keystore a certificate and key to fill the BIOP
      Parameters:
      ctx - Server or Client context to use.
      cert - Byte array with the certificate in DER encoding.
      key - Byte array with the Private Key file in PEM format.
      sslAidxRsa - Certificate index SSL_AIDX_RSA or SSL_AIDX_DSA.
      Returns:
      true if success, false otherwise.

    • addChainCertificateRaw

      public static boolean addChainCertificateRaw(long ctx, byte[] cert)
      Add a certificate to the certificate chain. Certs should be added in order starting with the issuer of the host certs and working up the certificate chain to the CA.
      Use keystore a certificate chain to fill the BIOP
      Parameters:
      ctx - Server or Client context to use.
      cert - Byte array with the certificate in DER encoding.
      Returns:
      true if success, false otherwise.

    • addClientCACertificateRaw

      public static boolean addClientCACertificateRaw(long ctx, byte[] cert)
      Add a CA certificate we accept as issuer for peer certs
      Parameters:
      ctx - Server or Client context to use.
      cert - Byte array with the certificate in DER encoding.
      Returns:
      true if success, false otherwise.