Package com.wolfssl

Class WolfSSLSession

  • public class WolfSSLSession
extends java.lang.Object
    Wraps a native WolfSSL session object and contains methods directly related to the SSL/TLS session.
    Version:
    1.0, August 2013
    Author:
    wolfSSL

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      int accept()
      Waits for an SSL client to initiate the SSL/TLS handshake.
      int checkDomainName​(java.lang.String dn)
      Adds a domain check to the list of checks performed during the peer verification.
      java.lang.String cipherGetName()
      Returns the cipher suite name associated with the WolfSSL session in String format.
      int connect()
      Initializes an SSL/TLS handshake with a server.
      int disableCRL()
      Turns off Certificate Revocation List (CRL) checking.
      int dtls()
      Used to determine if the SSL session has been configured to use DTLS.
      int dtlsGetCurrentTimeout()
      Returns the current timeout value in seconds for the SSL session.
      java.net.InetSocketAddress dtlsGetPeer()
      Gets the InetSocketAddress of the DTLS peer.
      int dtlsGotTimeout()
      Performs the actions needed to retry the last retransmit, including adjusting the timeout value.
      int dtlsSetPeer​(java.net.InetSocketAddress peer)
      Sets the DTLS peer.
      int enableCRL​(int options)
      Turns on Certificate Revocation List (CRL) checking when verifying certificates.
      protected void finalize()  
      void freeSSL()
      Frees an allocated SSL session.
      int getAeadMacSize()
      Allows caller to determine the negotiated aead mac size from the handshake.
      byte[] getAlpnSelected()
      Get the ALPN protocol selected by the client/server for this session.
      int getBulkCipher()
      Allows caller to determine the negotiated bulk cipher algorithm from the handshake.
      long getCacheSize()
      Gets the cache size is set at compile time.
      int getCipherBlockSize()
      Allows callers to determine the negotiated cipher block size from the handshake.
      int getCipherType()
      Allows caller to determine the negotiated cipher type from the handshake.
      byte[] getClientWriteIV()
      Allows retrieval of the client write IV (initialization vector) from the handshake process.
      byte[] getClientWriteKey()
      Allows retrieval of the client write key from the handshake process.
      long getCurrentCipher()
      Returns a pointer to the native WOLFSSL_CIPHER object being used in with the SSL session.
      int getError​(int ret)
      Returns a unique error code describing why the previous API function call resulted in an error return code.
      int getFd()
      Returns the file descriptor used as the input/output facility for the SSL connection.
      int getHmacSize()
      Allows the caller to determine the negotiated (h)mac size from the handshake.
      int getHmacType()
      Allows caller to determine the negotiated (h)mac type from the handshake.
      int getKeySize()
      Allows retrieval of the key size from the handshake process.
      byte[] getMacSecret​(int verify)
      Allows retrieval of the Hmac/Mac secret from the handshake process.
      long getOptions()
      Gets the options to use for the WOLFSSL structure.
      long getPeerCertificate()
      Gets the native (long) WOLFSSL_X509 pointer to the peer's certificate.
      java.lang.String getPeerX509AltName​(long x509)
      Gets the peer X509 certificate's altname information.
      java.lang.String getPeerX509Issuer​(long x509)
      Gets the peer X509 certificate's issuer information.
      java.lang.String getPeerX509Subject​(long x509)
      Gets the peer X509 certificate's subject information.
      java.lang.String getPskIdentity()
      Returns the PSK identity.
      java.lang.String getPskIdentityHint()
      Returns the PSK identity hint.
      byte[] getServerWriteIV()
      Allows retrieval of the server write IV (initialization vector) from the handshake process.
      byte[] getServerWriteKey()
      Allows retrieval of the server write key from the handshake process.
      long getSession()
      Returns a pointer to the current session used in the given SSL object.
      byte[] getSessionID()
      Returns the session ID.
      long getSessTimeout()
      Gets the timeout in seconds in the given WOLFSSL_SESSION.
      int getShutdown()
      Getter function to tell if shutdown has been sent or received
      int getSide()
      Allows retrieval of the side of this wolfSSL connection.
      long getTimeout()
      Gets the timeout in seconds in the given SSL object.
      int getUsingNonblock()
      Allows the application to determine if wolfSSL is using non-blocking I/O.
      java.lang.String getVersion()
      Returns the SSL/TLS version being used with this session object in String format.
      boolean gotCloseNotify()
      Returns true if the last alert received by this session was a close_notify alert from the peer.
      boolean handshakeDone()
      Used to determine if the handshake has been completed.
      int isTLSv1_1()
      Allows callers to determine if the negotiated protocol version is at least TLS version 1.1 or greater.
      int loadCRL​(java.lang.String path, int type, int monitor)
      Loads CRL files into wolfSSL from the specified path.
      int read​(byte[] data, int sz)
      Reads bytes from the SSL session and returns the read bytes as a byte array.
      int read​(byte[] data, int sz, int timeout)
      Reads bytes from the SSL session and returns the read bytes as a byte array, using socket timeout value in milliseconds.
      int sessionReused()
      Determine if a reused session was negotiated during the SSL handshake.
      void setAcceptState()
      Sets the WOLFSSL to be a server
      int setAlpnProtos​(byte[] alpnProtos)
      Set ALPN extension protocol for this session.
      int setCipherList​(java.lang.String list)
      Sets the cipher suite list for a given SSL session.
      void setConnectState()
      Sets the WOLFSSL to be a client
      int setCRLCb​(WolfSSLMissingCRLCallback cb)
      Registers CRL callback to be called when CRL lookup fails.
      void setDecryptVerifyCtx​(java.lang.Object ctx)
      Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback Context.
      void setEccSharedSecretCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key ECC Shared Secret Callback Context.
      void setEccSignCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key ECC Signing Callback Context.
      void setEccVerifyCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key ECC Verification Callback Context.
      int setFd​(java.net.DatagramSocket sd)
      Assigns a DatagramSocket file descriptor as the input/output facility for the SSL connection.
      int setFd​(java.net.Socket sd)
      Assigns a Socket file descriptor as the input/output facility for the SSL connection.
      void setGenCookieCtx​(java.lang.Object ctx)
      Registers a context for the SSL session's DTLS cookie generation callback method.
      int setGroupMessages()
      Turns on grouping of the handshake messages where possible using the SSL session.
      void setIOReadCtx​(java.lang.Object ctx)
      Registers a context for the SSL session's receive callback method.
      void setIORecv​(WolfSSLIORecvCallback callback)
      Registers a receive callback for wolfSSL to get input data.
      void setIOSend​(WolfSSLIOSendCallback callback)
      Registers a send callback for wolfSSL to write output data.
      void setIOWriteCtx​(java.lang.Object ctx)
      Registers a context for the SSL session's send callback method.
      void setMacEncryptCtx​(java.lang.Object ctx)
      Allows caller to set the Atomic Record Processing Mac/Encrypt Callback Context.
      long setOptions​(long op)
      Sets the options to use for the WOLFSSL structure.
      void setPskClientCb​(WolfSSLPskClientCallback callback)
      Allows caller to set the PSK client callback at the WolfSSLSession level.
      void setPskServerCb​(WolfSSLPskServerCallback callback)
      Allows caller to set the PSK server identity and key at the WolfSSLSession level.
      void setRsaDecCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key RSA Private Decrypt Callback Context.
      void setRsaEncCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key RSA Public Encrypt Callback Context.
      void setRsaSignCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key RSA Signing Callback Context.
      void setRsaVerifyCtx​(java.lang.Object ctx)
      Allows caller to set the Public Key RSA Verification Callback Context.
      int setSession​(long session)
      Sets the session to be used when the SSL object is used to create a SSL/TLS connection.
      long setSessTimeout​(long t)
      Sets the timeout in seconds in the given WOLFSSL_SESSION.
      long setTimeout​(long t)
      Sets the timeout in seconds in the given SSL object.
      int setTlsHmacInner​(byte[] inner, long sz, int content, int verify)
      Allows caller to set the Hmac Inner vector for message sending/receiving.
      int setTmpDH​(byte[] p, int pSz, byte[] g, int gSz)
      Sets up the group parameters to be used if the server negotiates a cipher suite that uses DHE.
      int setTmpDHFile​(java.lang.String fname, int format)
      Sets up the group parameters from the specified file to be used if the server negotiates a cipher suite that uses DHE.
      void setUsingNonblock​(int nonblock)
      Informs wolfSSL session that the underlying I/O is non-blocking.
      void setVerify​(int mode, WolfSSLVerifyCallback callback)
      Sets the verification method for remote peers and also allows a verify callback to be registered with the SSL session.
      int shutdownSSL()
      Shuts down the active SSL/TLS connection using the SSL session.
      int shutdownSSL​(int timeout)
      Shuts down the active SSL/TLS connection using the SSL session and provided read timeout value in milliseconds.
      int useCertificateBuffer​(byte[] in, long sz, int format)
      Loads a certificate buffer into the SSL object.
      int useCertificateChainBuffer​(byte[] in, long sz)
      Loads a certificate chain buffer into the SSL object.
      int useCertificateChainFile​(java.lang.String file)
      Loads a chain of certificates into the SSL session object.
      int useCertificateFile​(java.lang.String file, int format)
      Loads a certificate file into the SSL session object.
      int usePrivateKeyBuffer​(byte[] in, long sz, int format)
      Loads a private key buffer into the SSL object.
      int usePrivateKeyFile​(java.lang.String file, int format)
      Loads a private key file into the SSL session object.
      int usePskIdentityHint​(java.lang.String hint)
      Sets the identity hint for this session.
      int useSessionTicket()
      Enable session tickets for this session.
      int useSNI​(byte type, byte[] data)  
      int write​(byte[] data, int length)
      Write bytes from a byte array to the SSL connection.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • WolfSSLSession

        public WolfSSLSession​(WolfSSLContext ctx)
               throws WolfSSLException
        Creates a new SSL/TLS session.
        Parameters:
        ctx - WolfSSLContext object used to create SSL session.
        Throws:
        WolfSSLException - if session object creation failed.

    • Method Detail

      • useCertificateFile

        public int useCertificateFile​(java.lang.String file,
                              int format)
                       throws java.lang.IllegalStateException
        Loads a certificate file into the SSL session object. This file is provided by the file parameter. The format paramenter specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the wolfSSL examples for proper usage.
        Parameters:
        file - a file containing the certificate to be loaded into the wolfSSL SSL session object.
        format - format of the certificates pointed to by file . Possible options are SSL_FILETYPE_ASN1, for DER-encoded certificates, or SSL_FILETYPE_PEM for PEM-encoded certificates.
        Returns:
        SSL_SUCCESS upon success, SSL_BAD_FILE upon bad input file, otherwise SSL_FAILURE. Possible failure causes may be that the file is in the wrong format, the format argument was given incorrectly, the file doesn't exist, can't be read, or is corrupted, an out of memory condition occurs, or the Base16 decoding fails on the file.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        WolfSSLContext.useCertificateFile(String, int)

      • usePrivateKeyFile

        public int usePrivateKeyFile​(java.lang.String file,
                             int format)
                      throws java.lang.IllegalStateException
        Loads a private key file into the SSL session object. This file is provided by the file parameter. The format paramenter specifies the format type of the file - either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM. Please see the wolfSSL examples for proper usage.
        Parameters:
        file - a file containing the private key to be loaded into the wolfSSL SSL session.
        format - format of the private key pointed to by file . Possible options are SSL_FILETYPE_ASN1, for a DER-encoded key, or SSL_FILETYPE_PEM for a PEM-encoded key.
        Returns:
        SSL_SUCCESS upon success, SSL_BAD_FILE upon bad input file, otherwise SSL_FAILURE. Possible failure causes may be that the file is in the wrong format, the format argument was given incorrectly, the file doesn't exist, can't be read, or is corrupted, an out of memory condition occurs, the Base16 decoding fails on the file, or the key file is encrypted but no password is provided.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        WolfSSLContext.usePrivateKeyFile(String, int)

      • useCertificateChainFile

        public int useCertificateChainFile​(java.lang.String file)
                            throws java.lang.IllegalStateException
        Loads a chain of certificates into the SSL session object. The file containing the certificate chain is provided by the file parameter and must contain PEM-formatted certificates. This function will process up to MAX_CHAIN_DEPTH (default = 9, defined in internal.h) certificates, plus the subject cert.
        Parameters:
        file - path to the file containing the chain of certificates to be loaded into the wolfSSL SSL session. Certificates must be in PEM format.
        Returns:
        SSL_SUCCESS on success, SSL_BAD_FILE upon bad input file, otherwise SSL_FAILURE. If the function call fails, possible causes might include: the file is in the wrong format, the file doesn't exist, can't be read, or is corrupted, or an out of memory condition occurs.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        WolfSSLContext.useCertificateFile(String, int), useCertificateFile(String, int)

      • setFd

        public int setFd​(java.net.Socket sd)
          throws java.lang.IllegalStateException
        Assigns a Socket file descriptor as the input/output facility for the SSL connection.
        Parameters:
        sd - Socket to be used as input/output facility.
        Returns:
        SSL_SUCCESS on success, otherwise SSL_FAILURE.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getFd()

      • setFd

        public int setFd​(java.net.DatagramSocket sd)
          throws java.lang.IllegalStateException
        Assigns a DatagramSocket file descriptor as the input/output facility for the SSL connection. This can be used when using DatagramSocket objects with DTLS.
        Parameters:
        sd - Socket to be used as input/output facility.
        Returns:
        SSL_SUCCESS on success, otherwise SSL_FAILURE.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getFd()

      • setUsingNonblock

        public void setUsingNonblock​(int nonblock)
                      throws java.lang.IllegalStateException,
                             WolfSSLJNIException
        Informs wolfSSL session that the underlying I/O is non-blocking. After an application creates a SSL session (native WOLFSSL object), if it will be used with a non-blocking socket, this method should be called. This lets the SSL session know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.
        Parameters:
        nonblock - value used to set non-blocking flag on the SSL session. Use 1 to specify non-blocking, otherwise 0.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getUsingNonblock(), dtlsGotTimeout(), dtlsGetCurrentTimeout()

      • getUsingNonblock

        public int getUsingNonblock()
                     throws java.lang.IllegalStateException,
                            WolfSSLJNIException
        Allows the application to determine if wolfSSL is using non-blocking I/O. After an application created an SSL session object, if it will be used with a non-blocking socket, call setUsingNonblock() on it. This lets the SSL session object know that receiving EWOULDBLOCK means that the recvfrom call would block rather than that it timed out.
        Returns:
        1 if the underlying I/O is non-blocking, otherwise 0 if blocking.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setUsingNonblock(int), setSession(long)

      • getFd

        public int getFd()
          throws java.lang.IllegalStateException,
                 WolfSSLJNIException
        Returns the file descriptor used as the input/output facility for the SSL connection. Typically this will be a socket file descriptor.
        Returns:
        SSL session file descriptor
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setFd(Socket)

      • connect

        public int connect()
            throws java.lang.IllegalStateException
        Initializes an SSL/TLS handshake with a server. This function is called on the client side. When called, the underlying communication channel should already be set up.

        connect() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, connect() will return when the underlying I/O could not satisfy the needs of connect() to continue the handshake. In this case, a call to getError will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to connect() when the underlying I/O is ready and wolfSSL will pick up where it left off.

        If the underlying I/O is blocking, connect() will only return once the handshake has been finished or an error occurred.

        wolfSSL takes a different approach to certificate verification than OpenSSL does. The default policy for clients is to verify the server, meaning that if the application doesn't load CA certificates to verify the server, it will get a connect error, "unable to verify" (-155). If the application wants to mimic OpenSSL behavior of having connect() succeed even if verifying the server fails (and reducing security), the application can do this by calling:

        WolfSSLContext#setVerify(ctx, SSL_VERIFY_NONE, 0);

        before calling newSSL(), though it's not recommended.

        Returns:
        SSL_SUCCESS if successful, otherwise SSL_FATAL_ERROR if an error occurred. To get a more detailed error code, call getError().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • write

        public int write​(byte[] data,
                 int length)
          throws java.lang.IllegalStateException
        Write bytes from a byte array to the SSL connection. If necessary, write() will negotiate an SSL/TLS session if the handshake has not already been performed yet by connect or accept.

        write() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, write() will return when the underlying I/O could not satisfy the needs of write() to continue. In this case, a call to getError will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to write() when the underlying I/O is ready.

        If the underlying I/O is blocking, write() will only return once the buffer data of size length has been completely written or an error occurred.

        Parameters:
        data - data buffer which will be sent to peer
        length - size, in bytes, of data to send to the peer
        Returns:
        the number of bytes written upon success. 0 will be returned upon failure. SSL_FATAL_ERRORupon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and the application needs to call write() again. BAD_FUNC_ARC when bad arguments are used. Use getError to get a specific error code.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • read

        public int read​(byte[] data,
                int sz)
         throws java.lang.IllegalStateException
        Reads bytes from the SSL session and returns the read bytes as a byte array. The bytes read are removed from the internal receive buffer.

        If necessary, read() will negotiate an SSL/TLS session if the handshake has not already been performed yet by connect() or accept().

        The SSL/TLS protocol uses SSL records which have a maximum size of 16kB. As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to read() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not-yet-decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to read().

        Parameters:
        data - buffer where the data read from the SSL connection will be placed.
        sz - number of bytes to read into data
        Returns:
        the number of bytes read upon success. SSL_FAILURE will be returned upon failure which may be caused by either a clean (close notify alert) shutdown or just that the peer closed the connection. SSL_FATAL_ERROR upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and the application needs to call read() again. Use getError to get a specific error code. BAD_FUNC_ARC when bad arguments are used.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • read

        public int read​(byte[] data,
                int sz,
                int timeout)
         throws java.lang.IllegalStateException,
                java.net.SocketTimeoutException
        Reads bytes from the SSL session and returns the read bytes as a byte array, using socket timeout value in milliseconds. The bytes read are removed from the internal receive buffer.

        If necessary, read() will negotiate an SSL/TLS session if the handshake has not already been performed yet by connect() or accept().

        The SSL/TLS protocol uses SSL records which have a maximum size of 16kB. As such, wolfSSL needs to read an entire SSL record internally before it is able to process and decrypt the record. Because of this, a call to read() will only be able to return the maximum buffer size which has been decrypted at the time of calling. There may be additional not-yet-decrypted data waiting in the internal wolfSSL receive buffer which will be retrieved and decrypted with the next call to read().

        Parameters:
        data - buffer where the data read from the SSL connection will be placed.
        sz - number of bytes to read into data
        timeout - read timeout, milliseconds.
        Returns:
        the number of bytes read upon success. SSL_FAILURE will be returned upon failure which may be caused by either a clean (close notify alert) shutdown or just that the peer closed the connection. SSL_FATAL_ERROR upon failure when either an error occurred or, when using non-blocking sockets, the SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE error was received and the application needs to call read() again. Use getError to get a specific error code. BAD_FUNC_ARC when bad arguments are used.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        java.net.SocketTimeoutException - if socket timeout occurs

      • accept

        public int accept()
           throws java.lang.IllegalStateException
        Waits for an SSL client to initiate the SSL/TLS handshake. This method is called on the server side. When it is called, the underlying communication channel has already been set up.

        accept() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, accept() will return when the underlying I/O could not satisfy the needs of accept() to continue the handshake. In this case, a call to getError() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to accept() when data is available to be read and wolfSSL will pick up where it left off. When using a non-blocking socket, nothing needs to be done, but select() can be used to check for the required condition.

        If the underlying I/O is blocking, accept() will only return once the handshake has been finished or an error occurred.

        Returns:
        SSL_SUCCESS on success. SSL_FATAL_ERROR if an error occurred. To get a more detailed error code, call getError().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getError(int), connect()

      • shutdownSSL

        public int shutdownSSL()
                throws java.lang.IllegalStateException
        Shuts down the active SSL/TLS connection using the SSL session. This function will try to send a "close notify" alert to the peer, with read timeout disabled (set to infinite).

        The calling application can choose to wait for the peer to send its "close notify" alert in response or just go ahead and shut down the underlying connection after directly calling shutdownSSL (to save resources). Either option is allowed by the TLS specification. If the underlying connection will be used again in the future, the complete two-directional shutdown procedure must be performed to keep synchronization intact between the peers.

        shutdownSSL() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, shutdownSSL() will return an error if the underlying I/O could not satisfy the needs of shutdownSSL() to continue. In this case, a call to getError() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to shutdownSSL() when the underlying I/O is ready.

        Returns:
        SSL_SUCCESS on success, SSL_FATAL_ERROR upon failure. Call getError() for a more specific error code.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        shutdownSSL(int), freeSSL(long), WolfSSLContext.free()

      • shutdownSSL

        public int shutdownSSL​(int timeout)
                throws java.lang.IllegalStateException,
                       java.net.SocketTimeoutException
        Shuts down the active SSL/TLS connection using the SSL session and provided read timeout value in milliseconds. This function will try to send a "close notify" alert to the peer.

        The calling application can choose to wait for the peer to send its "close notify" alert in response or just go ahead and shut down the underlying connection after directly calling shutdownSSL (to save resources). Either option is allowed by the TLS specification. If the underlying connection will be used again in the future, the complete two-directional shutdown procedure must be performed to keep synchronization intact between the peers.

        shutdownSSL() works with both blocking and non-blocking I/O. When the underlying I/O is non-blocking, shutdownSSL() will return an error if the underlying I/O could not satisfy the needs of shutdownSSL() to continue. In this case, a call to getError() will yield either SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE. The calling process must then repeat the call to shutdownSSL() when the underlying I/O is ready.

        Parameters:
        timeout - read timeout, milliseconds.
        Returns:
        SSL_SUCCESS on success, SSL_FATAL_ERROR upon failure. Call getError() for a more specific error code.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        java.net.SocketTimeoutException - if read timeout occurs.
        See Also:
        freeSSL(long), WolfSSLContext.free()

      • getError

        public int getError​(int ret)
             throws java.lang.IllegalStateException
        Returns a unique error code describing why the previous API function call resulted in an error return code. The return value of the previous function is passed to getError() through ret.

        After getError() is called and returns the unique error code, getErrorString() may be called to get a human- readable error string.

        Parameters:
        ret - return value of the previous function which resulted in an error return code.
        Returns:
        the unique error code describing why the previous API function failed. SSL_ERROR_NONE will be returned if ret is less than 0.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        WolfSSL.getErrorString(long)

      • setSession

        public int setSession​(long session)
               throws java.lang.IllegalStateException
        Sets the session to be used when the SSL object is used to create a SSL/TLS connection. For session resumption, before calling shutdownSSL() with your session object, an application should save the session ID from the object with a call to getSession(), which returns a pointer to the session. Later, the application should create a new SSL session object and assign the saved session with setSession(). At this point, the application may call connect() and wolfSSL will try to resume the session.
        Parameters:
        session - pointer to the native WOLFSSL_SESSION structure used to set the session for the SSL session object.
        Returns:
        SSL_SUCCESS upon successfully setting the session. SSL_FAILURE will be returned on failure. This could be caused by the session cache being disabled, or if the session has timed out.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getSession()

      • getSession

        public long getSession()
                throws java.lang.IllegalStateException
        Returns a pointer to the current session used in the given SSL object. The native WOLFSSL_SESSION pointed to contains all the necessary information required to perform a session resumption and reestablishment the connection without a new handshake.

        For session resumption, before calling shutdownSSL() with your session object, an appliation should save the session ID from the object with a call to getSession(), which returns a pointer to the session. Later, the application should create a new SSL object and assign the saved session with setSession. At this point, the application may call connect() and wolfSSL will try to resume the session.

        Returns:
        a pointer to the current SSL session object on success. null if ssl is null, the SSL session cache is disabled, wolfSSL doesn't have the session ID available, or mutex functions fail.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        setSession(long)

      • getSessionID

        public byte[] getSessionID()
                    throws java.lang.IllegalStateException
        Returns the session ID.
        Returns:
        the session ID, or a empty array if unable to get valid session ID
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        setSession(long)

      • getCacheSize

        public long getCacheSize()
                  throws java.lang.IllegalStateException
        Gets the cache size is set at compile time. This function returns the current cache size which has been set at compile time.
        Returns:
        size of compile time cache.
        Throws:
        java.lang.IllegalStateException - WolfSSLSession has been freed

      • setSessTimeout

        public long setSessTimeout​(long t)
                    throws java.lang.IllegalStateException
        Sets the timeout in seconds in the given WOLFSSL_SESSION.
        Parameters:
        t - time in seconds to set
        Returns:
        WolfSSL.SSL_SUCCESS on success, WolfSSL.JNI_SESSION_UNAVAILABLE if underlying session is unavailable, or negative values on failure.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        setSession(long), getSession(long)

      • getSessTimeout

        public long getSessTimeout()
                    throws java.lang.IllegalStateException
        Gets the timeout in seconds in the given WOLFSSL_SESSION.
        Returns:
        current timeout in seconds
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        setSession(long), getSession(long)

      • setTimeout

        public long setTimeout​(long t)
                throws java.lang.IllegalStateException
        Sets the timeout in seconds in the given SSL object.
        Parameters:
        t - time in seconds to set
        Returns:
        WOLFSSL_SUCCESS on success, negative values on failure.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        setSession(long), getSession(long)

      • getTimeout

        public long getTimeout()
                throws java.lang.IllegalStateException
        Gets the timeout in seconds in the given SSL object.
        Returns:
        current timeout in seconds
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        setSession(long), getSession(long)

      • setCipherList

        public int setCipherList​(java.lang.String list)
                  throws java.lang.IllegalStateException
        Sets the cipher suite list for a given SSL session. The ciphers in the list should be sorted in order of preference from highest to lowest. Each call to setCipherList() resets the cipher suite list for the specific SSL session to the provided list each time time the method is called.

        The cipher suite list, list, is a null-terminated text String, and colon-delimited list. For example, one possible list may be:

        "DHE-RSA-AES256-SHA256:DHE-RSA-AES128-SHA256:AES256-SHA256"

        Valid cipher values are the full name values from the cipher_names[] array in the native wolfSSL src/internal.c:

        Parameters:
        list - null-terminated text string and colon-delimited list of cipher suites to use with the specified SSL context.
        Returns:
        SSL_SUCCESS upon success. SSL_FAILURE upon failure.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        WolfSSLContext.setCipherList(String)

      • dtlsGetCurrentTimeout

        public int dtlsGetCurrentTimeout()
                          throws java.lang.IllegalStateException,
                                 WolfSSLJNIException
        Returns the current timeout value in seconds for the SSL session. When using non-blocking sockets, something in the user code needs to decide when to check for available recv data and how long it has been waiting. The value returned by this method indicates how long the application should wait.
        Returns:
        the current DTLS timeout value in seconds, NOT_COMPILED_IN if wolfSSL was not built with DTLS support.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        dtls(), dtlsGetPeer(), dtlsGotTimeout(), dtlsSetPeer(InetSocketAddress)

      • dtlsGotTimeout

        public int dtlsGotTimeout()
                   throws java.lang.IllegalStateException,
                          WolfSSLJNIException
        Performs the actions needed to retry the last retransmit, including adjusting the timeout value. When using non-blocking sockets with DTLS, this method should be called on the SSL session when the controlling code thinks the transmission has timed out.
        Returns:
        SSL_SUCCESS upon success. SSL_FATAL_ERROR if there have been too many retransmissions/timeouts without getting a response from the peer. NOT_COMPILED_IN if wolfSSL was not compiled with DTLS support.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        dtlsGetCurrentTimeout(), dtlsGetPeer(), dtlsSetPeer(InetSocketAddress), dtls()

      • dtlsSetPeer

        public int dtlsSetPeer​(java.net.InetSocketAddress peer)
                throws java.lang.IllegalStateException
        Sets the DTLS peer.
        Parameters:
        peer - DTLS peer's InetSocketAddress
        Returns:
        SSL_SUCCESS upon success, SSL_FAILURE upon failure, SSL_NOT_IMPLEMENTED if wolfSSL was not compiled with DTLS support.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        dtlsGetCurrentTimeout(), dtlsGetPeer(), dtlsGotTimeout(), dtls()

      • dtlsGetPeer

        public java.net.InetSocketAddress dtlsGetPeer()
                                       throws java.lang.IllegalStateException
        Gets the InetSocketAddress of the DTLS peer.
        Returns:
        DTLS peer's InetSocketAddress upon success, null upon failure.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        dtlsGetCurrentTimeout(), dtlsGotTimeout(), dtlsSetPeer(InetSocketAddress), dtls()

      • sessionReused

        public int sessionReused()
                  throws java.lang.IllegalStateException,
                         WolfSSLJNIException
        Determine if a reused session was negotiated during the SSL handshake. If session resumption is being used, and the client has proposed to reuse a given session, this method will notify the application if the requested session has been negotiated after the handshake has completed.
        Returns:
        1 if the session was reused, 0 if a new session needed to be negotiated.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setSession(long), getSession()

      • getPeerX509Issuer

        public java.lang.String getPeerX509Issuer​(long x509)
                                   throws java.lang.IllegalStateException,
                                          WolfSSLJNIException
        Gets the peer X509 certificate's issuer information.
        Parameters:
        x509 - pointer (long) to native WOLFSSL_X509 structure, obtained from getPeerCertificate().
        Returns:
        String representation of the peer's issuer information
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getPeerCertificate(), getPeerX509Subject(long), getVersion(), getCurrentCipher()

      • getPeerX509Subject

        public java.lang.String getPeerX509Subject​(long x509)
                                    throws java.lang.IllegalStateException,
                                           WolfSSLJNIException
        Gets the peer X509 certificate's subject information.
        Parameters:
        x509 - pointer (long) to native WOLFSSL_X509 structure, obtained from getPeerCertificate().
        Returns:
        String representation of the peer's subject information
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getPeerCertificate(), getPeerX509Issuer(long), getVersion(), getCurrentCipher()

      • getPeerX509AltName

        public java.lang.String getPeerX509AltName​(long x509)
                                    throws java.lang.IllegalStateException,
                                           WolfSSLJNIException
        Gets the peer X509 certificate's altname information. This method may be repeatedly called to get the next altname, if any, from the peer cert. If no more altnames are available, null will be returned.
        Parameters:
        x509 - pointer (long) to native WOLFSSL_X509 structure, obtained from getPeerCertificate().
        Returns:
        String representation of the peer's subject information
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getPeerCertificate(), getPeerX509Issuer(long), getPeerX509Subject(long), getVersion(), getCurrentCipher()

      • getVersion

        public java.lang.String getVersion()
                            throws java.lang.IllegalStateException,
                                   WolfSSLJNIException
        Returns the SSL/TLS version being used with this session object in String format. Examples include "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2", "DTLS", and "DTLS 1.2".
        Returns:
        SSL/TLS protocol version being used in String format, or "unknown".
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error

      • getCurrentCipher

        public long getCurrentCipher()
                      throws java.lang.IllegalStateException,
                             WolfSSLJNIException
        Returns a pointer to the native WOLFSSL_CIPHER object being used in with the SSL session. This pointer can be used with the getCipherName() function to get the name of the current cipher suite being used.
        Returns:
        pointer (long) to the native WOLFSSL_CIPHER object currently used with the SSL session.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        cipherGetName()

      • checkDomainName

        public int checkDomainName​(java.lang.String dn)
                    throws java.lang.IllegalStateException,
                           WolfSSLJNIException
        Adds a domain check to the list of checks performed during the peer verification. wolfSSL by default check the peer certificate for a valid date range and a verified signature. Calling this function before connect() or accept() will add a domain name check to the list of checks to perform.
        Parameters:
        dn - domain name to check against the peer certificate when received.
        Returns:
        SSL_SUCCESS on success, SSL_FAILURE if a memory error was encountered.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error

      • setTmpDH

        public int setTmpDH​(byte[] p,
                    int pSz,
                    byte[] g,
                    int gSz)
             throws java.lang.IllegalStateException,
                    WolfSSLJNIException
        Sets up the group parameters to be used if the server negotiates a cipher suite that uses DHE.
        Parameters:
        p - Diffie-Hellman prime number parameter
        pSz - size of p
        g - Diffie-Hellman "generator" parameter
        gSz - size of g
        Returns:
        SSL_SUCCESS on success. MEMORY_E if a memory error was encountered. SIDE_ERROR if this function is called on an SSL client instead of an SSL server.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        accept()

      • setTmpDHFile

        public int setTmpDHFile​(java.lang.String fname,
                        int format)
                 throws java.lang.IllegalStateException,
                        WolfSSLJNIException
        Sets up the group parameters from the specified file to be used if the server negotiates a cipher suite that uses DHE.
        Parameters:
        fname - path to Diffie-Hellman parameter file
        format - format of DH parameter file, either SSL_FILETYPE_ASN1 or SSL_FILETYPE_PEM.
        Returns:
        SSL_SUCCESS on success. MEMORY_E if a memory error was encountered. SIDE_ERROR if this function is called on an SSL client instead of an SSL server, SSL_BAD_FILETYPE if the specified format is incorrect, SSL_BAD_FILE if there is a problem with the input file.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setTmpDH(byte[], int, byte[], int)

      • setGroupMessages

        public int setGroupMessages()
                     throws java.lang.IllegalStateException,
                            WolfSSLJNIException
        Turns on grouping of the handshake messages where possible using the SSL session.
        Returns:
        SSL_SUCCESS upon success. BAD_FUNC_ARG if the input session is null.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setGroupMessages()

      • setIOReadCtx

        public void setIOReadCtx​(java.lang.Object ctx)
                  throws java.lang.IllegalStateException,
                         WolfSSLJNIException
        Registers a context for the SSL session's receive callback method. By default, wolfSSL sets the file descriptor passed to setFd() as the context when wolfSSL is using the system's TCP library. If you've registered your own receive callback you may want to set a specific context for the session.

        For example, if you're using memory buffers, the context may be a pointer to an object describing where and how to access the memory buffers.

        Parameters:
        ctx - context object to be registered with the SSL session's receive callback method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setIOWriteCtx(Object), WolfSSLContext.setIORecv(WolfSSLIORecvCallback), WolfSSLContext.setIOSend(WolfSSLIOSendCallback)

      • setIOWriteCtx

        public void setIOWriteCtx​(java.lang.Object ctx)
                   throws java.lang.IllegalStateException,
                          WolfSSLJNIException
        Registers a context for the SSL session's send callback method. By default, wolfSSL sets the file descriptor passed to setFd() as the context when wolfSSL is using the system's TCP library. If you've registered your own send callback, you may want to set a specific context for the session.

        For example, if you're using memory buffers the context may be a pointer to an object describing where and how to access the memory buffers.

        Parameters:
        ctx - context object to be registered with the SSL session's send callback method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setIOReadCtx(Object), WolfSSLContext.setIOSend(WolfSSLIOSendCallback), WolfSSLContext.setIORecv(WolfSSLIORecvCallback)

      • setGenCookieCtx

        public void setGenCookieCtx​(java.lang.Object ctx)
                     throws java.lang.IllegalStateException,
                            WolfSSLJNIException
        Registers a context for the SSL session's DTLS cookie generation callback method. By default, wolfSSL sets the file descriptor passed to setFd() as the context when wolfSSL is using the system's TCP library. If the application has registered its own DTLS gen cookie callback, it may need to set a specific context for the cookie generation method.
        Parameters:
        ctx - context object to be registered with the SSL session's cookie generation method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setGenCookie(WolfSSLGenCookieCallback)

      • loadCRL

        public int loadCRL​(java.lang.String path,
                   int type,
                   int monitor)
            throws java.lang.IllegalStateException,
                   WolfSSLJNIException
        Loads CRL files into wolfSSL from the specified path. This method loads a list of CRL files into wolfSSL. The files can be in either PEM or DER format, as specified by the type parameter.
        Parameters:
        path - path to directory containing CRL files
        type - type of files in path, either SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1 .
        monitor - OR'd list of flags to indicate if wolfSSL should monitor the provided CRL directory for changes. Flag values include WOLFSSL_CRL_MONITOR to indicate that the directory should be monitored and WOLFSSL_CRL_START_MON to start the monitor.
        Returns:
        SSL_SUCCESS upon success
        SSL_FATAL_ERROR if enabling the internal CertManager fails
        BAD_FUNC_ARG if the SSL pointer is null
        BAD_PATH_ERROR if there is an error opening the provided directory
        MEMORY_E if a memory error occurred
        MONITOR_RUNNING_E if the CRL monitor is already running
        THREAD_CREATE_E if there was an error when creating the CRL monitoring thread.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        enableCRL(int), disableCRL(), setCRLCb(WolfSSLMissingCRLCallback), WolfSSLContext.enableCRL(int), WolfSSLContext.disableCRL(), WolfSSLContext.setCRLCb(WolfSSLMissingCRLCallback)

      • cipherGetName

        public java.lang.String cipherGetName()
                               throws java.lang.IllegalStateException,
                                      WolfSSLJNIException
        Returns the cipher suite name associated with the WolfSSL session in String format.
        Returns:
        String representation of the cipher suite associated with the corresponding WolfSSL session.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getCurrentCipher()

      • getMacSecret

        public byte[] getMacSecret​(int verify)
                    throws java.lang.IllegalStateException,
                           WolfSSLJNIException
        Allows retrieval of the Hmac/Mac secret from the handshake process. The verify parameter specifies whether this is for verification of a peer message.
        Parameters:
        verify - specifies whether this if for verification of a peer message.
        Returns:
        a valid secret upon success, or null for an error state. The size of the secret can be obtained from getHmacSize().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getHmacSize()

      • getClientWriteKey

        public byte[] getClientWriteKey()
                         throws java.lang.IllegalStateException,
                                WolfSSLJNIException
        Allows retrieval of the client write key from the handshake process.
        Returns:
        a valid key buffer upon success, or null for an error state. The size of the key can be obtained from getKeySize().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getKeySize(), getClientWriteIV()

      • getClientWriteIV

        public byte[] getClientWriteIV()
                        throws java.lang.IllegalStateException,
                               WolfSSLJNIException
        Allows retrieval of the client write IV (initialization vector) from the handshake process.
        Returns:
        a valid IV buffer upon success, or null for an error state. The size of the IV can be obtained from getCipherBlockSize().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getCipherBlockSize(), getClientWriteKey()

      • getServerWriteKey

        public byte[] getServerWriteKey()
                         throws java.lang.IllegalStateException,
                                WolfSSLJNIException
        Allows retrieval of the server write key from the handshake process.
        Returns:
        a valid key buffer upon success, or null for an error state. The size of the key can be obtained from getKeySize().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getKeySize(), getServerWriteIV()

      • getServerWriteIV

        public byte[] getServerWriteIV()
                        throws java.lang.IllegalStateException,
                               WolfSSLJNIException
        Allows retrieval of the server write IV (initialization vector) from the handshake process.
        Returns:
        a valid IV buffer upon success, or null for an error state. The size of the IV can be obtained from getCipherBlockSize().
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        getCipherBlockSize(), getServerWriteKey()

      • getKeySize

        public int getKeySize()
               throws java.lang.IllegalStateException
        Allows retrieval of the key size from the handshake process.
        Returns:
        the key size in bytes upon success. BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getClientWriteKey(), getServerWriteKey()

      • getSide

        public int getSide()
            throws java.lang.IllegalStateException
        Allows retrieval of the side of this wolfSSL connection.
        Returns:
        WOLFSSL_SERVER_END or WOLFSSL_CLIENT_END depending on the side of the wolfSSL session object. BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getClientWriteKey(), getServerWriteKey()

      • isTLSv1_1

        public int isTLSv1_1()
              throws java.lang.IllegalStateException
        Allows callers to determine if the negotiated protocol version is at least TLS version 1.1 or greater.
        Returns:
        1 for true, 0 for false. BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getSide()

      • getBulkCipher

        public int getBulkCipher()
                  throws java.lang.IllegalStateException
        Allows caller to determine the negotiated bulk cipher algorithm from the handshake.
        Returns:
        If successful, the call will return one of the following:
        WolfSSL.wolfssl_cipher_null
        WolfSSL.wolfssl_des
        WolfSSL.wolfssl_triple_des
        WolfSSL.wolfssl_aes
        WolfSSL.wolfssl_aes_gcm
        WolfSSL.wolfssl_aes_ccm
        WolfSSL.wolfssl_camellia
        WolfSSL.hc128
        WolfSSL.rabbit
        BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getCipherBlockSize(), getKeySize()

      • getCipherBlockSize

        public int getCipherBlockSize()
                       throws java.lang.IllegalStateException
        Allows callers to determine the negotiated cipher block size from the handshake.
        Returns:
        the size in bytes of the cipher block size upon success, BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getBulkCipher(), getKeySize()

      • getAeadMacSize

        public int getAeadMacSize()
                   throws java.lang.IllegalStateException
        Allows caller to determine the negotiated aead mac size from the handshake. For cipher type WOLFSSL_AEAD_TYPE.
        Returns:
        the size in bytes of the aead mac size upon success, BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getBulkCipher(), getKeySize()

      • getHmacSize

        public int getHmacSize()
                throws java.lang.IllegalStateException
        Allows the caller to determine the negotiated (h)mac size from the handshake. For cipher types except WOLFSSL_AEAD_TYPE.
        Returns:
        the size in bytes of the (h)mac size upon success, BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getBulkCipher(), getHmacType()

      • getHmacType

        public int getHmacType()
                throws java.lang.IllegalStateException
        Allows caller to determine the negotiated (h)mac type from the handshake. For cipher types except WOLFSSL_AEAD_TYPE.
        Returns:
        If successful, the call will return one of the following:

        WolfSSL.MD5
        WolfSSL.SHA
        WolfSSL.SHA256
        WolfSSL.SHA394

        BAD_FUNC_ARG or SSL_FATAL_ERROR will be returned for an error state.

        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getBulkCipher(), getHmacSize()

      • getCipherType

        public int getCipherType()
                  throws java.lang.IllegalStateException
        Allows caller to determine the negotiated cipher type from the handshake.
        Returns:
        If successful, the call will return one of the following:

        WolfSSL.WOLFSSL_BLOCK_TYPE
        WolfSSL.WOLFSSL_STREAM_TYPE
        WolfSSL.WOLFSSL_AEAD_TYPE

        BAD_FUNC_ARG will be returned for an error state.

        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getBulkCipher(), getHmacType()

      • setTlsHmacInner

        public int setTlsHmacInner​(byte[] inner,
                           long sz,
                           int content,
                           int verify)
                    throws java.lang.IllegalStateException
        Allows caller to set the Hmac Inner vector for message sending/receiving. The result is written to inner which should be at least getHmacSize() bytes. The size of the message is specified by sz, content is the type of message, and verify specifies whether this is a verification of a peer message. Valid for cipher types excluding WOLFSSL_AEAD_TYPE.
        Parameters:
        inner - inner HMAC vector to set
        sz - size of the message, in bytes
        content - type of the message
        verify - specifies if this is a verification of a peer message.
        Returns:
        1 upon success, BAD_FUNC_ARG for an error state.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        See Also:
        getBulkCipher(), getHmacType()

      • setMacEncryptCtx

        public void setMacEncryptCtx​(java.lang.Object ctx)
                      throws java.lang.IllegalStateException,
                             WolfSSLJNIException
        Allows caller to set the Atomic Record Processing Mac/Encrypt Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's MAC/Encrypt method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setMacEncryptCb(WolfSSLMacEncryptCallback)

      • setDecryptVerifyCtx

        public void setDecryptVerifyCtx​(java.lang.Object ctx)
                         throws java.lang.IllegalStateException,
                                WolfSSLJNIException
        Allows caller to set the Atomic User Record Processing Decrypt/Verify Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's decrypt/verify method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setDecryptVerifyCb(WolfSSLDecryptVerifyCallback)

      • setEccSignCtx

        public void setEccSignCtx​(java.lang.Object ctx)
                   throws java.lang.IllegalStateException,
                          WolfSSLJNIException
        Allows caller to set the Public Key ECC Signing Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's ECC signing method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setEccSignCb(WolfSSLEccSignCallback)

      • setEccVerifyCtx

        public void setEccVerifyCtx​(java.lang.Object ctx)
                     throws java.lang.IllegalStateException,
                            WolfSSLJNIException
        Allows caller to set the Public Key ECC Verification Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's ECC verification method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setEccVerifyCb(WolfSSLEccVerifyCallback)

      • setRsaSignCtx

        public void setRsaSignCtx​(java.lang.Object ctx)
                   throws java.lang.IllegalStateException,
                          WolfSSLJNIException
        Allows caller to set the Public Key RSA Signing Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's RSA signing method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setRsaSignCb(WolfSSLRsaSignCallback)

      • setRsaVerifyCtx

        public void setRsaVerifyCtx​(java.lang.Object ctx)
                     throws java.lang.IllegalStateException,
                            WolfSSLJNIException
        Allows caller to set the Public Key RSA Verification Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's RSA verification method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setRsaVerifyCb(WolfSSLRsaVerifyCallback)

      • setRsaEncCtx

        public void setRsaEncCtx​(java.lang.Object ctx)
                  throws java.lang.IllegalStateException,
                         WolfSSLJNIException
        Allows caller to set the Public Key RSA Public Encrypt Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's RSA public encrypt method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setRsaEncCb(WolfSSLRsaEncCallback)

      • setRsaDecCtx

        public void setRsaDecCtx​(java.lang.Object ctx)
                  throws java.lang.IllegalStateException,
                         WolfSSLJNIException
        Allows caller to set the Public Key RSA Private Decrypt Callback Context.
        Parameters:
        ctx - context object to be registered with the SSL session's RSA private decrypt method.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setRsaDecCb(WolfSSLRsaDecCallback)

      • setPskClientCb

        public void setPskClientCb​(WolfSSLPskClientCallback callback)
                    throws java.lang.IllegalStateException,
                           WolfSSLJNIException
        Allows caller to set the PSK client callback at the WolfSSLSession level. This provides a method for the user to set the identity, hint, and key the WolfSSLSession level. The PSK client callback can also be set at the WolfSSLContext level, allowing the user to set it once for all SSL/TLS sessions that are created from the WolfSSLContext. The callback should return the length of the key in octets or 0 for error. The ssl parameter is available for the user's convenience. hint is the client PSK hint. identity is the client identity, with a maximum size in characters of idMaxLen. key is the client key, with a maximum size in bytes of keyMaxLen. An example callback can be found in examples/MyPskClientCallback.java. If the user sets the PSK client callback at both WolfSSLSession and WolfSSLContext levels, the context-level one will be used.
        Parameters:
        callback - object to be registered as the PSK client callback for the WolfSSLSession. The signature of this object and corresponding method must match that as shown in WolfSSLPskClientCallback.java, inside pskClientCallback().
        Throws:
        java.lang.IllegalStateException - WolfSSLSession has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        WolfSSLContext.setPskClientCb(WolfSSLPskClientCallback), WolfSSLContext.setPskServerCb(WolfSSLPskServerCallback), WolfSSLContext.usePskIdentityHint(String), setPskServerCb(WolfSSLPskServerCallback), getPskIdentity(), getPskIdentityHint()

      • handshakeDone

        public boolean handshakeDone()
        Used to determine if the handshake has been completed.
        Returns:
        true if the handshake is completed -- false if not.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • setConnectState

        public void setConnectState()
        Sets the WOLFSSL to be a client
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • setAcceptState

        public void setAcceptState()
        Sets the WOLFSSL to be a server
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed\

      • setVerify

        public void setVerify​(int mode,
                      WolfSSLVerifyCallback callback)
               throws java.lang.IllegalStateException
        Sets the verification method for remote peers and also allows a verify callback to be registered with the SSL session. If no verify callback is desired, null can be used for callback.

        The verification mode of peer certificates is a logically OR'd list of flags. The possible flag values include:

        SSL_VERIFY_NONE
        Client mode: the client will not verify the certificate received from teh server and the handshake will continue as normal.
        Server mode: the server will not send a certificate request to the client. As such, client verification will not be enabled.

        SSL_VERIFY_PEER
        Client mode: the client will verify the certificate received from the server during the handshake. This is turned on by default in wolfSSL, therefore, using this option has no effect.
        Server mode: the server will send a certificate request to the client and verify the client certificate received.

        SSL_VERIFY_FAIL_IF_NO_PEER_CERT
        Client mode: no effect when used on the client side.
        Server mode: the verification will fail on the server side if the client fails to send a certificate when requested to do so (when using SSL_VERIFY_PEER on the SSL server).

        Parameters:
        mode - verification type
        callback - custom verification callback to register with the SSL session. If no callback is desired, null may be used.
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • setOptions

        public long setOptions​(long op)
                throws java.lang.IllegalStateException
        Sets the options to use for the WOLFSSL structure. Example options are WolfSSL.SSL_OP_NO_SSLv3
        Parameters:
        op - bit mask of options to set
        Returns:
        returns the revised options bit mask on success
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • getOptions

        public long getOptions()
                throws java.lang.IllegalStateException
        Gets the options to use for the WOLFSSL structure. Example options are WolfSSL.SSL_OP_NO_SSLv3
        Returns:
        returns the revised options bit mask on success
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed

      • gotCloseNotify

        public boolean gotCloseNotify()
        Returns true if the last alert received by this session was a close_notify alert from the peer.
        Returns:
        true if close_notify has been received, otherwise false

      • setIORecv

        public void setIORecv​(WolfSSLIORecvCallback callback)
               throws java.lang.IllegalStateException,
                      WolfSSLJNIException
        Registers a receive callback for wolfSSL to get input data. By default, wolfSSL uses EmbedReceive() in src/io.c as the callback. This uses the system's TCP recv() function. The user can register a function to get input from memory, some other network module, or from anywhere. Please see the EmbedReceive() function in src/io.c as a guide for how the function should work and for error codes.

        In particular, IO_ERR_WANT_READ should be returned for non-blocking receive when no data is ready.

        Parameters:
        callback - method to be registered as the receive callback for the wolfSSL context. The signature of this function must follow that as shown in WolfSSLIORecvCallback#receiveCallback(WolfSSLSession, byte[], int, long).
        Throws:
        java.lang.IllegalStateException - WolfSSLContext has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setIOSend(WolfSSLIOSendCallback)

      • setIOSend

        public void setIOSend​(WolfSSLIOSendCallback callback)
               throws java.lang.IllegalStateException,
                      WolfSSLJNIException
        Registers a send callback for wolfSSL to write output data. By default, wolfSSL uses EmbedSend() in src/io.c as the callback, which uses the system's TCP send() function. The user can register a function to send output to memory, some other network module, or to anywhere. Please see the EmbedSend() function in src/io.c as a guide for how the function should work and for error codes.

        In particular, IO_ERR_WANT_WRITE should be returned for non-blocking send when the action cannot be taken yet.

        Parameters:
        callback - method to be registered as the send callback for the wolfSSL context. The signature of this function must follow that as shown in WolfSSLIOSendCallback#sendCallback(WolfSSLSession, byte[], int, Object).
        Throws:
        java.lang.IllegalStateException - WolfSSLSession has been freed
        WolfSSLJNIException - Internal JNI error
        See Also:
        setIORecv(WolfSSLIORecvCallback)

      • useSNI

        public int useSNI​(byte type,
                  byte[] data)
           throws java.lang.IllegalStateException
        Throws:
        java.lang.IllegalStateException

      • useSessionTicket

        public int useSessionTicket()
                     throws java.lang.IllegalStateException
        Enable session tickets for this session.
        Returns:
        WolfSSL.SSL_SUCCESS on success, otherwise negative.
        Throws:
        java.lang.IllegalStateException - WolfSSLSession has been freed

      • setAlpnProtos

        public int setAlpnProtos​(byte[] alpnProtos)
                  throws java.lang.IllegalStateException
        Set ALPN extension protocol for this session. Calls native SSL_set_alpn_protos() at native level. Format starts with length, where length does not include length byte itself. Example format: byte[] p = "http/1.1".getBytes();
        Parameters:
        alpnProtos - ALPN protocols, encoded as byte array vector
        Returns:
        WolfSSL.SSL_SUCCESS on success, otherwise negative.
        Throws:
        java.lang.IllegalStateException

      • getAlpnSelected

        public byte[] getAlpnSelected()
                       throws java.lang.IllegalStateException
        Get the ALPN protocol selected by the client/server for this session.
        Returns:
        byte array representation of selected protocol, starting with length byte. Length does not include length byte itself.
        Throws:
        java.lang.IllegalStateException - WolfSSLSession has been freed

      • getShutdown

        public int getShutdown()
        Getter function to tell if shutdown has been sent or received
        Returns:
        WolfSSL.SSL_SENT_SHUTDOWN or WolfSSL.SSL_RECEIVED_SHUTDOWN

      • finalize

        protected void finalize()
                 throws java.lang.Throwable
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.lang.Throwable