Return to SSLCTX.java CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / axTLS / bindings / java

axTLS

    1: /*
    2:  * Copyright (c) 2007, Cameron Rich
    3:  * 
    4:  * All rights reserved.
    5:  * 
    6:  * Redistribution and use in source and binary forms, with or without 
    7:  * modification, are permitted provided that the following conditions are met:
    8:  *
    9:  * * Redistributions of source code must retain the above copyright notice, 
   10:  *   this list of conditions and the following disclaimer.
   11:  * * Redistributions in binary form must reproduce the above copyright notice, 
   12:  *   this list of conditions and the following disclaimer in the documentation 
   13:  *   and/or other materials provided with the distribution.
   14:  * * Neither the name of the axTLS project nor the names of its contributors 
   15:  *   may be used to endorse or promote products derived from this software 
   16:  *   without specific prior written permission.
   17:  *
   18:  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   19:  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   20:  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   21:  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
   22:  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
   23:  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
   24:  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
   25:  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
   26:  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
   27:  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
   28:  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   29:  */
   30: 
   31: /*
   32:  * A wrapper around the unmanaged interface to give a semi-decent Java API
   33:  */
   34: 
   35: package axTLSj;
   36: 
   37: import java.net.*;
   38: 
   39: /**
   40:  * @class SSLCTX
   41:  * @ingroup java_api 
   42:  * @brief A base object for SSLServer/SSLClient.
   43:  */
   44: public class SSLCTX
   45: {
   46:     /**
   47:      * A reference to the real client/server context.
   48:      */
   49:     protected int m_ctx;
   50: 
   51:     /**
   52:      * @brief Establish a new client/server context.
   53:      *
   54:      * This function is called before any client/server SSL connections are 
   55:      * made.  If multiple threads are used, then each thread will have its 
   56:      * own SSLCTX context. Any number of connections may be made with a single 
   57:      * context. 
   58:      *
   59:      * Each new connection will use the this context's private key and 
   60:      * certificate chain. If a different certificate chain is required, then a 
   61:      * different context needs to be be used.
   62:      *
   63:      * @param options [in]  Any particular options. At present the options
   64:      * supported are:
   65:      * - SSL_SERVER_VERIFY_LATER (client only): Don't stop a handshake if the 
   66:      * server authentication fails. The certificate can be authenticated later 
   67:      * with a call to verifyCert().
   68:      * - SSL_CLIENT_AUTHENTICATION (server only): Enforce client authentication
   69:      * i.e. each handshake will include a "certificate request" message from 
   70:      * the server.
   71:      * - SSL_DISPLAY_BYTES (full mode build only): Display the byte sequences
   72:      * during the handshake.
   73:      * - SSL_DISPLAY_STATES (full mode build only): Display the state changes
   74:      * during the handshake.
   75:      * - SSL_DISPLAY_CERTS (full mode build only): Display the certificates that
   76:      * are passed during a handshake.
   77:      * - SSL_DISPLAY_RSA (full mode build only): Display the RSA key details 
   78:      * that are passed during a handshake.
   79:      *
   80:      * @param num_sessions [in] The number of sessions to be used for session
   81:      * caching. If this value is 0, then there is no session caching.
   82:      * 
   83:      * If this option is null, then the default internal private key/
   84:      * certificate pair is used (if CONFIG_SSL_USE_DEFAULT_KEY is set). 
   85:      * 
   86:      * The resources used by this object are automatically freed.  
   87:      * @return A client/server context.
   88:      */
   89:     protected SSLCTX(int options, int num_sessions)
   90:     {
   91:         m_ctx = axtlsj.ssl_ctx_new(options, num_sessions);
   92:     }
   93: 
   94:     /**
   95:      * @brief Remove a client/server context.
   96:      *
   97:      * Frees any used resources used by this context. Each connection will be 
   98:      * sent a "Close Notify" alert (if possible).
   99:      */
  100:     public void dispose()
  101:     {
  102:         axtlsj.ssl_ctx_free(m_ctx);
  103:     }
  104: 
  105:     /**
  106:      * @brief Read the SSL data stream.
  107:      * @param ssl [in] An SSL object reference.
  108:      * @param rh [out] After a successful read, the decrypted data can be 
  109:      * retrieved with rh.getData(). It will be null otherwise.
  110:      * @return The number of decrypted bytes:
  111:      * - if > 0, then the handshaking is complete and we are returning the 
  112:      * number of decrypted bytes. 
  113:      * - SSL_OK if the handshaking stage is successful (but not yet complete).  
  114:      * - < 0 if an error.
  115:      * @see ssl.h for the error code list.
  116:      * @note Use rh before doing any successive ssl calls.
  117:      */
  118:     public int read(SSL ssl, SSLReadHolder rh)
  119:     {
  120:         return axtlsj.ssl_read(ssl.m_ssl, rh);
  121:     }
  122: 
  123:     /**
  124:      * @brief Write to the SSL data stream.
  125:      * @param ssl [in] An SSL obect reference.
  126:      * @param out_data [in] The data to be written
  127:      * @return The number of bytes sent, or if < 0 if an error.
  128:      * @see ssl.h for the error code list.
  129:      */
  130:     public int write(SSL ssl, byte[] out_data)
  131:     {
  132:         return axtlsj.ssl_write(ssl.m_ssl, out_data, out_data.length);
  133:     }
  134: 
  135:     /**
  136:      * @brief Write to the SSL data stream.
  137:      * @param ssl [in] An SSL obect reference.
  138:      * @param out_data [in] The data to be written
  139:      * @param out_len [in] The number of bytes to be written
  140:      * @return The number of bytes sent, or if < 0 if an error.
  141:      * @see ssl.h for the error code list.
  142:      */
  143:     public int write(SSL ssl, byte[] out_data, int out_len)
  144:     {
  145:         return axtlsj.ssl_write(ssl.m_ssl, out_data, out_len);
  146:     }
  147: 
  148:     /**
  149:      * @brief Find an ssl object based on a Socket reference.
  150:      *
  151:      * Goes through the list of SSL objects maintained in a client/server 
  152:      * context to look for a socket match.
  153:      * @param s [in] A reference to a <A HREF="http://java.sun.com/j2se/1.4.2/docs/api">Socket</A> object.
  154:      * @return A reference to the SSL object. Returns null if the object 
  155:      * could not be found.
  156:      */
  157:     public SSL find(Socket s)
  158:     {
  159:         int client_fd = axtlsj.getFd(s);
  160:         return new SSL(axtlsj.ssl_find(m_ctx, client_fd));
  161:     }
  162: 
  163:     /**
  164:      * @brief Authenticate a received certificate.
  165:      * 
  166:      * This call is usually made by a client after a handshake is complete 
  167:      * and the context is in SSL_SERVER_VERIFY_LATER mode.
  168:      * @param ssl [in] An SSL object reference.
  169:      * @return SSL_OK if the certificate is verified.
  170:      */
  171:     public int verifyCert(SSL ssl)
  172:     {
  173:         return axtlsj.ssl_verify_cert(ssl.m_ssl);
  174:     }
  175: 
  176:     /**
  177:      * @brief Force the client to perform its handshake again.
  178:      *
  179:      * For a client this involves sending another "client hello" message.
  180:      * For the server is means sending a "hello request" message.
  181:      *
  182:      * This is a blocking call on the client (until the handshake completes).
  183:      * @param ssl [in] An SSL object reference.
  184:      * @return SSL_OK if renegotiation instantiation was ok
  185:      */
  186:     public int renegotiate(SSL ssl)
  187:     {
  188:         return axtlsj.ssl_renegotiate(ssl.m_ssl);
  189:     }
  190: 
  191:     /**
  192:      * @brief Load a file into memory that is in binary DER or ASCII PEM format.
  193:      *
  194:      * These are temporary objects that are used to load private keys,
  195:      * certificates etc into memory.
  196:      * @param obj_type [in] The format of the file. Can be one of:
  197:      * - SSL_OBJ_X509_CERT (no password required)
  198:      * - SSL_OBJ_X509_CACERT (no password required)
  199:      * - SSL_OBJ_RSA_KEY (AES128/AES256 PEM encryption supported)
  200:      * - SSL_OBJ_P8 (RC4-128 encrypted data supported)
  201:      * - SSL_OBJ_P12 (RC4-128 encrypted data supported)
  202:      *
  203:      * PEM files are automatically detected (if supported).
  204:      * @param filename [in] The location of a file in DER/PEM format.
  205:      * @param password [in] The password used. Can be null if not required.
  206:      * @return SSL_OK if all ok
  207:      */
  208:     public int objLoad(int obj_type, String filename, String password)
  209:     {
  210:         return axtlsj.ssl_obj_load(m_ctx, obj_type, filename, password);
  211:     }
  212: 
  213:     /**
  214:      * @brief Transfer binary data into the object loader.
  215:      *
  216:      * These are temporary objects that are used to load private keys,
  217:      * certificates etc into memory.
  218:      * @param obj_type [in] The format of the memory data.
  219:      * @param data [in] The binary data to be loaded.
  220:      * @param len [in] The amount of data to be loaded.
  221:      * @param password [in] The password used. Can be null if not required.
  222:      * @return SSL_OK if all ok
  223:      */
  224: 
  225:     public int objLoad(int obj_type, byte[] data, int len, String password)
  226:     {
  227:         return axtlsj.ssl_obj_memory_load(m_ctx, obj_type, data, len, password);
  228:     }
  229: }