Class SSLContext


  • public final class SSLContext
    extends java.lang.Object
    • Field Detail

      • MAX_ALPN_NPN_PROTO_SIZE

        private static final int MAX_ALPN_NPN_PROTO_SIZE
        See Also:
        Constant Field Values
    • Constructor Detail

      • SSLContext

        private SSLContext()
    • Method Detail

      • 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.
      • setContextId

        public static void setContextId​(long ctx,
                                        java.lang.String id)
        Set Session context id. Usually host:port combination.
        Parameters:
        ctx - Context to use.
        id - String that uniquely identifies this context.
      • 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.
      • setCipherSuite

        @Deprecated
        public static boolean setCipherSuite​(long ctx,
                                             java.lang.String ciphers)
                                      throws java.lang.Exception
        Cipher Suite available for negotiation in SSL handshake.
        This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the client is permitted to negotiate in the SSL handshake phase. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotiation with the reconfigured Cipher Suite after the HTTP request was read but before the HTTP response is sent.
        Parameters:
        ctx - Server or Client context to use.
        ciphers - An SSL cipher specification.
        Returns:
        true if successful
        Throws:
        java.lang.Exception - if an error happened
      • setCipherSuite

        public static boolean setCipherSuite​(long ctx,
                                             java.lang.String ciphers,
                                             boolean tlsv13)
                                      throws java.lang.Exception
        Cipher Suite available for negotiation in SSL handshake.
        This complex directive uses a colon-separated cipher-spec string consisting of OpenSSL cipher specifications to configure the Cipher Suite the client is permitted to negotiate in the SSL handshake phase. Notice that this directive can be used both in per-server and per-directory context. In per-server context it applies to the standard SSL handshake when a connection is established. In per-directory context it forces a SSL renegotiation with the reconfigured Cipher Suite after the HTTP request was read but before the HTTP response is sent.
        Parameters:
        ctx - Server or Client context to use.
        ciphers - An SSL cipher specification.
        tlsv13 - true if the ciphers are for TLSv1.3
        Returns:
        true if successful
        Throws:
        java.lang.Exception - if an error happened
      • setCertificateChainFile

        public static boolean setCertificateChainFile​(long ctx,
                                                      java.lang.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 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 successful
      • setCertificateChainBio

        public static boolean setCertificateChainBio​(long ctx,
                                                     long bio,
                                                     boolean skipfirst)
        Set BIO 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 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. Otherwsie the browsers will be confused in this situation.

        Parameters:
        ctx - Server or Client context to use.
        bio - BIO of PEM-encoded Server CA Certificates.
        skipfirst - Skip first certificate if chain file is inside certificate file.
        Returns:
        true if successful
      • setCertificate

        public static boolean setCertificate​(long ctx,
                                             java.lang.String cert,
                                             java.lang.String key,
                                             java.lang.String password)
                                      throws java.lang.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.
        Returns:
        true if successful
        Throws:
        java.lang.Exception - if an error happened
      • setCertificateBio

        public static boolean setCertificateBio​(long ctx,
                                                long certBio,
                                                long keyBio,
                                                java.lang.String password)
                                         throws java.lang.Exception
        Set Certificate

        Point setCertificate at a PEM encoded certificate stored in a BIO. 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.
        certBio - Certificate BIO.
        keyBio - Private Key BIO to use if not in cert.
        password - Certificate password. If null and certificate is encrypted, password prompt will be displayed.
        Returns:
        true if successful
        Throws:
        java.lang.Exception - if an error happened
      • setSessionCacheSize

        public static long setSessionCacheSize​(long ctx,
                                               long size)
        Set the size of the internal session cache. See man SSL_CTX_sess_set_cache_size
        Parameters:
        ctx - Server or Client context to use.
        size - the size of the cache
        Returns:
        the previous set value
      • getSessionCacheSize

        public static long getSessionCacheSize​(long ctx)
        Get the size of the internal session cache. See man SSL_CTX_sess_get_cache_size
        Parameters:
        ctx - Server or Client context to use.
        Returns:
        the current value
      • setSessionCacheTimeout

        public static long setSessionCacheTimeout​(long ctx,
                                                  long timeoutSeconds)
        Set the timeout for the internal session cache in seconds. See man SSL_CTX_set_timeout
        Parameters:
        ctx - Server or Client context to use.
        timeoutSeconds - the timeout of the cache
        Returns:
        the previous set value
      • getSessionCacheTimeout

        public static long getSessionCacheTimeout​(long ctx)
        Get the timeout for the internal session cache in seconds. See man SSL_CTX_get_timeout
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current value
      • 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 of the cache
        Returns:
        the previous set value
      • 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 current mode
      • sessionAccept

        public static long sessionAccept​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionAcceptGood

        public static long sessionAcceptGood​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionAcceptRenegotiate

        public static long sessionAcceptRenegotiate​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionCacheFull

        public static long sessionCacheFull​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionCbHits

        public static long sessionCbHits​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionConnect

        public static long sessionConnect​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionConnectGood

        public static long sessionConnectGood​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionConnectRenegotiate

        public static long sessionConnectRenegotiate​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionHits

        public static long sessionHits​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionMisses

        public static long sessionMisses​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionNumber

        public static long sessionNumber​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionTimeouts

        public static long sessionTimeouts​(long ctx)
        Session resumption statistics methods. See man SSL_CTX_sess_number
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionTicketKeyNew

        public static long sessionTicketKeyNew​(long ctx)
        TLS session ticket key resumption statistics.
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionTicketKeyResume

        public static long sessionTicketKeyResume​(long ctx)
        TLS session ticket key resumption statistics.
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionTicketKeyRenew

        public static long sessionTicketKeyRenew​(long ctx)
        TLS session ticket key resumption statistics.
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • sessionTicketKeyFail

        public static long sessionTicketKeyFail​(long ctx)
        TLS session ticket key resumption statistics.
        Parameters:
        ctx - Server or Client context to use
        Returns:
        the current number
      • setSessionTicketKeys

        public static void setSessionTicketKeys​(long ctx,
                                                SessionTicketKey[] keys)
        Set TLS session ticket keys.

        The first key in the list is the primary key. Tickets dervied from the other keys in the list will be accepted but updated to a new ticket using the primary key. This is useful for implementing ticket key rotation. See RFC 5077

        Parameters:
        ctx - Server or Client context to use
        keys - the SessionTicketKeys
      • setSessionTicketKeys0

        private static void setSessionTicketKeys0​(long ctx,
                                                  byte[] keys)
        Set TLS session keys.
      • setCACertificateBio

        public static boolean setCACertificateBio​(long ctx,
                                                  long certBio)
        Set concatenated PEM-encoded CA Certificates for Client Auth
        This directive sets the all-in-one BIO where you can assemble the Certificates of Certification Authorities (CA) whose clients you deal with. These are used for Client Authentication. Such a BIO 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.
        Parameters:
        ctx - Server context to use.
        certBio - Directory of PEM-encoded CA Certificates for Client Auth.
        Returns:
        true if successful, false otherwise.
      • 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 a 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: 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.
      • 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.
      • setCertificateCallback

        public static void setCertificateCallback​(long ctx,
                                                  CertificateCallback callback)
        Allow to hook CertificateCallback into the certificate choosing process. This will call SSL_CTX_set_cert_cb and so replace the default verification callback used by openssl
        Parameters:
        ctx - Server or Client context to use.
        callback - the callback to call during certificate selection.
      • setSniHostnameMatcher

        public static void setSniHostnameMatcher​(long ctx,
                                                 SniHostNameMatcher matcher)
        Allow to hook SniHostNameMatcher into the sni processing. This will call SSL_CTX_set_tlsext_servername_callback and so replace the default callback used by openssl
        Parameters:
        ctx - Server or Client context to use.
        matcher - the matcher to call during sni hostname matching.
      • setKeyLogCallback

        public static boolean setKeyLogCallback​(long ctx,
                                                KeyLogCallback callback)
        Allow to hook KeyLogCallback into the debug infrastructor of the native TLS implementation. This will call SSL_CTX_set_keylog_callback and so replace the existing reference. This is intended for debugging use with tools like Wireshark.

        Warning: The log output will contain secret key material, and can be used to decrypt TLS sessions! The log output should be handled with the same care given to the private keys.

        Parameters:
        ctx - Server or Client context to use.
        callback - the callback to call when delivering debug output.
        Returns:
        true if the key-log callback was assigned, otherwise false if key-log callbacks are not supported.
      • protocolsToWireFormat

        private static byte[] protocolsToWireFormat​(java.lang.String[] protocols)
      • setNpnProtos0

        private static void setNpnProtos0​(long ctx,
                                          byte[] nextProtos,
                                          int selectorFailureBehavior)
      • setAlpnProtos0

        private static void setAlpnProtos0​(long ctx,
                                           byte[] alpnProtos,
                                           int selectorFailureBehavior)
      • setTmpDHLength

        public static void setTmpDHLength​(long ctx,
                                          int length)
        Set length of the DH to use.
        Parameters:
        ctx - Server context to use.
        length - the length.
      • setSessionIdContext

        public static boolean setSessionIdContext​(long ctx,
                                                  byte[] sidCtx)
        Set the context within which session be reused (server side only). See man SSL_CTX_set_session_id_context
        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.
      • setMode

        public static int setMode​(long ctx,
                                  int mode)
        Call SSL_CTX_set_mode
        Parameters:
        ctx - context to use
        mode - the mode
        Returns:
        the set mode.
      • getMode

        public static int getMode​(long ctx)
        Call SSL_CTX_get_mode
        Parameters:
        ctx - context to use
        Returns:
        the mode.
      • getSslCtx

        public static long getSslCtx​(long ctx)
        Returns the SSL_CTX.
      • setUseTasks

        public static void setUseTasks​(long ctx,
                                       boolean useTasks)
        Enable or disable producing of tasks that should be obtained via SSL.getTask(long) and run.
        Parameters:
        ctx - context to use
        useTasks - true to enable, false to disable.
      • addCertificateCompressionAlgorithm0

        private static int addCertificateCompressionAlgorithm0​(long ctx,
                                                               int direction,
                                                               int algorithmId,
                                                               CertificateCompressionAlgo algorithm)
      • setPrivateKeyMethod

        public static void setPrivateKeyMethod​(long ctx,
                                               SSLPrivateKeyMethod method)
        Set the SSLPrivateKeyMethod to use for the given SSLContext. This allows to offload private key operations if needed. This method is currently only supported when BoringSSL is used.
        Parameters:
        ctx - context to use
        method - method to use for the given context.
      • setPrivateKeyMethod

        public static void setPrivateKeyMethod​(long ctx,
                                               AsyncSSLPrivateKeyMethod method)
        Sets the AsyncSSLPrivateKeyMethod to use for the given SSLContext. This allows to offload private key operations if needed. This method is currently only supported when BoringSSL is used.
        Parameters:
        ctx - context to use
        method - method to use for the given context.
      • setSSLSessionCache

        public static void setSSLSessionCache​(long ctx,
                                              SSLSessionCache cache)
        Set the SSLSessionCache that will be used if session caching is enabled.
        Parameters:
        ctx - context to use.
        cache - cache to use for the given context.
      • setNumTickets

        public static boolean setNumTickets​(long ctx,
                                            int tickets)
        Set the number of TLSv1.3 session tickets that will be sent to the client after a full handshake. See SSL_CTX_set_num_tickets for more details.
        Parameters:
        ctx - context to use
        tickets - the number of tickets
        Returns:
        true if successful, false otherwise.
      • setCurvesList

        public static boolean setCurvesList​(long ctx,
                                            java.lang.String... curves)
        Sets the curves to use. See SSL_CTX_set1_curves_list.
        Parameters:
        ctx - context to use
        curves - the curves to use.
        Returns:
        true if successful, false otherwise.
      • setCurvesList0

        private static boolean setCurvesList0​(long ctx,
                                              java.lang.String curves)
      • setMaxCertList

        public static void setMaxCertList​(long ctx,
                                          int size)
        Set the maximum number of bytes for the certificate chain during handshake. See SSL_CTX_set_max_cert_list for more details.
        Parameters:
        ctx - context to use
        size - the maximum number of bytes