com.wolfssl
Class WolfSSLSession

java.lang.Object
  extended by com.wolfssl.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

Constructor Summary
WolfSSLSession(WolfSSLContext ctx)
          Creates a new SSL/TLS session.
 
Method Summary
 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.
 void freeSSL()
          Frees an allocated SSL session.
 int getAeadMacSize()
          Allows caller to determine the negotiated aead mac size from the handshake.
 int getBulkCipher()
          Allows caller to determine the negotiated bulk cipher algorithm from the handshake.
 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 CYASSL_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 getPeerCertificate()
          Gets the native (long) CYASSL_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.
 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.
 int getSide()
          Allows retrieval of the side of this wolfSSL connection.
 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.
 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 sessionReused()
          Determine if a reused session was negotiated during the SSL handshake.
 int setCipherList(java.lang.String list)
          Sets the cipher suite list for a given SSL session.
 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 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 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.
 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.
 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.
 int shutdownSSL()
          Shuts down the active SSL/TLS connection using the SSL session.
 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 write(byte[] data, int length)
          Write bytes from a byte array to the SSL connection.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, 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
Method Detail

useCertificateFile

public int useCertificateFile(java.lang.String file,
                              int format)
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 CyaSSL 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.
See Also:
WolfSSLContext.useCertificateFile(String, int)

usePrivateKeyFile

public int usePrivateKeyFile(java.lang.String file,
                             int format)
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 CyaSSL 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.
See Also:
WolfSSLContext.usePrivateKeyFile(String, int)

useCertificateChainFile

public int useCertificateChainFile(java.lang.String file)
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.
See Also:
WolfSSLContext.useCertificateFile(String, int), useCertificateFile(String, int)

setFd

public int setFd(java.net.Socket sd)
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.
See Also:
getFd()

setFd

public int setFd(java.net.DatagramSocket sd)
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.
See Also:
getFd()

setUsingNonblock

public void setUsingNonblock(int nonblock)
Informs wolfSSL session that the underlying I/O is non-blocking. After an application creates a SSL session (native CYASSL 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.
See Also:
getUsingNonblock(), dtlsGotTimeout(), dtlsGetCurrentTimeout()

getUsingNonblock

public int getUsingNonblock()
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.
See Also:
setUsingNonblock(int), setSession(long)

getFd

public int getFd()
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
See Also:
setFd(Socket)

connect

public int connect()
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 CyaSSL 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.

CyaSSL 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().

write

public int write(byte[] data,
                 int length)
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.

read

public int read(byte[] data,
                int sz)
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.

accept

public int accept()
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().
See Also:
getError(int), connect()

freeSSL

public void freeSSL()
Frees an allocated SSL session.

See Also:
WolfSSLContext.newContext(long), WolfSSLContext.free()

shutdownSSL

public int shutdownSSL()
Shuts down the active SSL/TLS connection using the SSL session. 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.

Returns:
SSL_SUCCESS on success, SSL_FATAL_ERROR upon failure. Call getError() for a more specific error code.
See Also:
freeSSL(long), WolfSSLContext.free()

getError

public int getError(int ret)
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 > 0.
See Also:
WolfSSL.getErrorString(long)

setSession

public int setSession(long session)
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 CYASSL_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.
See Also:
getSession()

getSession

public long getSession()
Returns a pointer to the current session used in the given SSL object. The native CYASSL_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. nullssl is null, the SSL session cache is disabled, wolfSSL doesn't have the session ID available, or mutex functions fail.
See Also:
setSession(long)

setCipherList

public int setCipherList(java.lang.String list)
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.
See Also:
WolfSSLContext.setCipherList(String)

dtlsGetCurrentTimeout

public int dtlsGetCurrentTimeout()
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, or NOT_COMPILED_IN if wolfSSL was not built with DTLS support.
See Also:
dtls(), dtlsGetPeer(), dtlsGotTimeout(), dtlsSetPeer(InetSocketAddress)

dtlsGotTimeout

public int dtlsGotTimeout()
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.
See Also:
dtlsGetCurrentTimeout(), dtlsGetPeer(), dtlsSetPeer(InetSocketAddress), dtls()

dtls

public int dtls()
Used to determine if the SSL session has been configured to use DTLS.

Returns:
1 if the SSL has been configured to use DTLS, otherwise, 0.
See Also:
dtlsGetCurrentTimeout(), dtlsGetPeer(), dtlsGotTimeout(), dtlsSetPeer(InetSocketAddress)

dtlsSetPeer

public int dtlsSetPeer(java.net.InetSocketAddress peer)
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.
See Also:
dtlsGetCurrentTimeout(), dtlsGetPeer(), dtlsGotTimeout(), dtls()

dtlsGetPeer

public java.net.InetSocketAddress dtlsGetPeer()
Gets the InetSocketAddress of the DTLS peer.

Returns:
DTLS peer's InetSocketAddress upon success, null upon failure.
See Also:
dtlsGetCurrentTimeout(), dtlsGotTimeout(), dtlsSetPeer(InetSocketAddress), dtls()

sessionReused

public int sessionReused()
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.
See Also:
setSession(long), getSession()

getPeerCertificate

public long getPeerCertificate()
Gets the native (long) CYASSL_X509 pointer to the peer's certificate. This can be used to retrieve further information about the peer's certificate (issuer, subject, alt name, etc.)

See Also:
getPeerX509Issuer(long), getPeerX509Subject(long), getVersion(), getCurrentCipher()

getPeerX509Issuer

public java.lang.String getPeerX509Issuer(long x509)
Gets the peer X509 certificate's issuer information.

Parameters:
x509 - pointer (long) to native CYASSL_X509 structure, obtained from getPeerCertificate().
Returns:
String representation of the peer's issuer information
See Also:
getPeerCertificate(), getPeerX509Subject(long), getVersion(), getCurrentCipher()

getPeerX509Subject

public java.lang.String getPeerX509Subject(long x509)
Gets the peer X509 certificate's subject information.

Parameters:
x509 - pointer (long) to native CYASSL_X509 structure, obtained from getPeerCertificate().
Returns:
String representation of the peer's subject information
See Also:
getPeerCertificate(), getPeerX509Issuer(long), getVersion(), getCurrentCipher()

getPeerX509AltName

public java.lang.String getPeerX509AltName(long x509)
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 CYASSL_X509 structure, obtained from getPeerCertificate().
Returns:
String representation of the peer's subject information
See Also:
getPeerCertificate(), getPeerX509Issuer(long), getPeerX509Subject(long), getVersion(), getCurrentCipher()

getVersion

public java.lang.String getVersion()
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".

getCurrentCipher

public long getCurrentCipher()
Returns a pointer to the native CYASSL_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 CYASSL_CIPHER object currently used with the SSL session.
See Also:
cipherGetName()

checkDomainName

public int checkDomainName(java.lang.String dn)
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.

setTmpDH

public 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.

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.
See Also:
accept()

setTmpDHFile

public 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.

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.
See Also:
setTmpDH(byte[], int, byte[], int)

useCertificateBuffer

public int useCertificateBuffer(byte[] in,
                                long sz,
                                int format)
Loads a certificate buffer into the SSL object. This method behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file.

Parameters:
in - input buffer containing the certificate to load
sz - size of the input buffer, in
format - format of the certificate buffer being loaded - either SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns:
SSL_SUCCESS upon success, SSL_BAD_FILETYPE if the file is in the wrong format, SSL_BAD_FILE if the file doesn't exist, can't be read, or is corrupted. MEMORY_E if an out of memory condition occurs, ASN_INPUT_E if Base16 decoding fails on the file, and BAD_FUNC_ARG if invalid input parameters are given.
See Also:
WolfSSLContext.loadVerifyBuffer(byte[], long, int), WolfSSLContext.useCertificateBuffer(byte[], long, int), WolfSSLContext.usePrivateKeyBuffer(byte[], long, int), WolfSSLContext.useCertificateChainBuffer(byte[], long), usePrivateKeyBuffer(byte[], long, int), useCertificateChainBuffer(byte[], long)

usePrivateKeyBuffer

public int usePrivateKeyBuffer(byte[] in,
                               long sz,
                               int format)
Loads a private key buffer into the SSL object. This method behaves like the non-buffered version, only differing in its ability to be called with a buffer as input rather than a file.

Parameters:
in - the input buffer containing the private key to be loaded
sz - the size of the input buffer, in
format - format of the certificate buffer being loaded - either SSL_FILETYPE_PEM or SSL_FILETYPE_ASN1
Returns:
SSL_SUCCESS upon success, SSL_BAD_FILETYPE if the file is in the wrong format, SSL_BAD_FILE if the file doesn't exist, can't be read, or is corrupted. MEMORY_E if an out of memory condition occurs, ASN_INPUT_E if Base16 decoding fails on the file, NO_PASSWORD if the key file is encrypted but no password is provided, and BAD_FUNC_ARG if invalid input parameters are given.
See Also:
WolfSSLContext.loadVerifyBuffer(byte[], long, int), WolfSSLContext.useCertificateBuffer(byte[], long, int), WolfSSLContext.usePrivateKeyBuffer(byte[], long, int), WolfSSLContext.useCertificateChainBuffer(byte[], long), useCertificateBuffer(byte[], long, int), useCertificateChainBuffer(byte[], long)

useCertificateChainBuffer

public int useCertificateChainBuffer(byte[] in,
                                     long sz)
Loads a certificate chain buffer into the SSL object. This method behaves like the non-buffered version, only differing in its ability to be called with a buffer as input instead of a file. The buffer must be in PEM format and start with the subject's certificate, ending with the root certificate.

Parameters:
in - the input buffer containing the PEM-formatted certificate chain to be loaded.
sz - the size of the input buffer, in
Returns:
SSL_SUCCESS upon success, SSL_BAD_FILETYPE if the file is in the wrong format, SSL_BAD_FILE if the file doesn't exist, can't be read, or is corrupted. MEMORY_E if an out of memory condition occurs, ASN_INPUT_E if Base16 decoding fails on the file, BUFFER_E if a chain buffer is bigger than the receiving buffer, and BAD_FUNC_ARG if invalid input parameters are given.
See Also:
WolfSSLContext.loadVerifyBuffer(byte[], long, int), WolfSSLContext.useCertificateBuffer(byte[], long, int), WolfSSLContext.usePrivateKeyBuffer(byte[], long, int), WolfSSLContext.useCertificateChainBuffer(byte[], long), useCertificateBuffer(byte[], long, int), usePrivateKeyBuffer(byte[], long, int)

setGroupMessages

public int setGroupMessages()
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.
See Also:
WolfSSLContext.setGroupMessages()

setIOReadCtx

public void setIOReadCtx(java.lang.Object ctx)
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.
See Also:
setIOWriteCtx(Object), WolfSSLContext.setIORecv(WolfSSLIORecvCallback), WolfSSLContext.setIOSend(WolfSSLIOSendCallback)

setIOWriteCtx

public void setIOWriteCtx(java.lang.Object ctx)
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.
See Also:
setIOReadCtx(Object), WolfSSLContext.setIOSend(WolfSSLIOSendCallback), WolfSSLContext.setIORecv(WolfSSLIORecvCallback)

setGenCookieCtx

public void setGenCookieCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setGenCookie(WolfSSLGenCookieCallback)

enableCRL

public int enableCRL(int options)
Turns on Certificate Revocation List (CRL) checking when verifying certificates. By default, CRL checking is off. options include CYASSL_CRL_CHECKALL which performs CRL checking on each certificate in the chain versus the leaf certificate only (which is default).

Parameters:
options - options to use when enabling CRL
Returns:
SSL_SUCCESS upon success. NOT_COMPILED_IN if wolfSSL was not compiled with CRL enabled. MEMORY_E if an out of memory condition occurs. BAD_FUNC_ARG if a pointer is not provided, and SSL_FAILURE if the CRL context cannot be initialized properly.
See Also:
disableCRL(), loadCRL(String, int, int), setCRLCb(WolfSSLMissingCRLCallback), WolfSSLContext.enableCRL(int), WolfSSLContext.disableCRL(), WolfSSLContext.setCRLCb(WolfSSLMissingCRLCallback)

disableCRL

public int disableCRL()
Turns off Certificate Revocation List (CRL) checking. By default, CRL checking is off. This function can be used to temporarily or permanently disable CRL checking for a given SSL session object that previously had CRL checking enabled.

Returns:
SSL_SUCCESS on success, BAD_FUNC_ARG if pointer is not provided.
See Also:
enableCRL(int), loadCRL(String, int, int), setCRLCb(WolfSSLMissingCRLCallback), WolfSSLContext.enableCRL(int), WolfSSLContext.disableCRL(), WolfSSLContext.setCRLCb(WolfSSLMissingCRLCallback)

loadCRL

public int loadCRL(java.lang.String path,
                   int type,
                   int monitor)
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 CYASSL_CRL_MONITOR to indicate that the directory should be monitored and CYASSL_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.
See Also:
enableCRL(int), disableCRL(), setCRLCb(WolfSSLMissingCRLCallback), WolfSSLContext.enableCRL(int), WolfSSLContext.disableCRL(), WolfSSLContext.setCRLCb(WolfSSLMissingCRLCallback)

setCRLCb

public int setCRLCb(WolfSSLMissingCRLCallback cb)
Registers CRL callback to be called when CRL lookup fails.

Parameters:
cb - callback to be registered with SSL session, called when CRL lookup fails.
Returns:
SSL_SUCCESS upon success, BAD_FUNC_ARG if SSL pointer is null.
See Also:
enableCRL(int), disableCRL(), loadCRL(String, int, int), WolfSSLContext.enableCRL(int), WolfSSLContext.disableCRL(), WolfSSLContext.setCRLCb(WolfSSLMissingCRLCallback)

cipherGetName

public java.lang.String cipherGetName()
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.
See Also:
getCurrentCipher()

getMacSecret

public byte[] getMacSecret(int verify)
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().
See Also:
getHmacSize()

getClientWriteKey

public byte[] getClientWriteKey()
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().
See Also:
getKeySize(), getClientWriteIV()

getClientWriteIV

public byte[] getClientWriteIV()
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().
See Also:
getCipherBlockSize(), getClientWriteKey()

getServerWriteKey

public byte[] getServerWriteKey()
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().
See Also:
getKeySize(), getServerWriteIV()

getServerWriteIV

public byte[] getServerWriteIV()
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().
See Also:
getCipherBlockSize(), getServerWriteKey()

getKeySize

public int getKeySize()
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.
See Also:
getClientWriteKey(), getServerWriteKey()

getSide

public int getSide()
Allows retrieval of the side of this wolfSSL connection.

Returns:
CYASSL_SERVER_END or CYASSL_CLIENT_END depending on the side of the wolfSSL session object. BAD_FUNC_ARG for an error state.
See Also:
getClientWriteKey(), getServerWriteKey()

isTLSv1_1

public int isTLSv1_1()
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.
See Also:
getSide()

getBulkCipher

public int getBulkCipher()
Allows caller to determine the negotiated bulk cipher algorithm from the handshake.

Returns:
If successful, the call will return one of the following:

WolfSSL.cyassl_cipher_null
WolfSSL.cyassl_des
WolfSSL.cyassl_triple_des
WolfSSL.cyassl_aes
WolfSSL.cyassl_aes_gcm
WolfSSL.cyassl_aes_ccm
WolfSSL.cyassl_camellia
WolfSSL.hc128
WolfSSL.rabbit

BAD_FUNC_ARG for an error state.

See Also:
getCipherBlockSize(), getKeySize()

getCipherBlockSize

public int getCipherBlockSize()
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.
See Also:
getBulkCipher(), getKeySize()

getAeadMacSize

public int getAeadMacSize()
Allows caller to determine the negotiated aead mac size from the handshake. For cipher type CYASSL_AEAD_TYPE.

Returns:
the size in bytes of the aead mac size upon success, BAD_FUNC_ARG for an error state.
See Also:
getBulkCipher(), getKeySize()

getHmacSize

public int getHmacSize()
Allows the caller to determine the negotiated (h)mac size from the handshake. For cipher types except CYASSL_AEAD_TYPE.

Returns:
the size in bytes of the (h)mac size upon success, BAD_FUNC_ARG for an error state.
See Also:
getBulkCipher(), getHmacType()

getHmacType

public int getHmacType()
Allows caller to determine the negotiated (h)mac type from the handshake. For cipher types except CYASSL_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.

See Also:
getBulkCipher(), getHmacSize()

getCipherType

public int getCipherType()
Allows caller to determine the negotiated cipher type from the handshake.

Returns:
If successful, the call will return one of the following:

WolfSSL.CYASSL_BLOCK_TYPE
WolfSSL.CYASSL_STREAM_TYPE
WolfSSL.CYASSL_AEAD_TYPE

BAD_FUNC_ARG will be returned for an error state.

See Also:
getBulkCipher(), getHmacType()

setTlsHmacInner

public int setTlsHmacInner(byte[] inner,
                           long sz,
                           int content,
                           int verify)
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 CYASSL_AEAD_TYPE.

Returns:
1 upon success, BAD_FUNC_ARG for an error state.
See Also:
getBulkCipher(), getHmacType()

setMacEncryptCtx

public void setMacEncryptCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setMacEncryptCb(WolfSSLMacEncryptCallback)

setDecryptVerifyCtx

public void setDecryptVerifyCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setDecryptVerifyCb(WolfSSLDecryptVerifyCallback)

setEccSignCtx

public void setEccSignCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setEccSignCb(WolfSSLEccSignCallback)

setEccVerifyCtx

public void setEccVerifyCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setEccVerifyCb(WolfSSLEccVerifyCallback)

setRsaSignCtx

public void setRsaSignCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setRsaSignCb(WolfSSLRsaSignCallback)

setRsaVerifyCtx

public void setRsaVerifyCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setRsaVerifyCb(WolfSSLRsaVerifyCallback)

setRsaEncCtx

public void setRsaEncCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setRsaEncCb(WolfSSLRsaEncCallback)

setRsaDecCtx

public void setRsaDecCtx(java.lang.Object ctx)
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.
See Also:
WolfSSLContext.setRsaDecCb(WolfSSLRsaDecCallback)