[Feature]Upload Modem source code
Change-Id: Id4294f30faced84d3e6fd6d5e61e1111bf287a37
diff --git a/mcu/interface/driver/cipher/include/ssl_api.h b/mcu/interface/driver/cipher/include/ssl_api.h
new file mode 100644
index 0000000..25fd30f
--- /dev/null
+++ b/mcu/interface/driver/cipher/include/ssl_api.h
@@ -0,0 +1,1452 @@
+/*****************************************************************************
+* Copyright Statement:
+* --------------------
+* This software is protected by Copyright and the information contained
+* herein is confidential. The software may not be copied and the information
+* contained herein may not be used or disclosed except with the written
+* permission of MediaTek Inc. (C) 2005
+*
+* BY OPENING THIS FILE, BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
+* THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("MEDIATEK SOFTWARE")
+* RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON
+* AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES,
+* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
+* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
+* NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE
+* SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR
+* SUPPLIED WITH THE MEDIATEK SOFTWARE, AND BUYER AGREES TO LOOK ONLY TO SUCH
+* THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. MEDIATEK SHALL ALSO
+* NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER'S
+* SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM.
+*
+* BUYER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE
+* LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE,
+* AT MEDIATEK'S OPTION, TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE,
+* OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO
+* MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
+*
+* THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE
+* WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF
+* LAWS PRINCIPLES. ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND
+* RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER
+* THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC).
+*
+*****************************************************************************/
+
+/*******************************************************************************
+ * Filename:
+ * ---------
+ * ssl_api.h
+ *
+ * Project:
+ * --------
+ * MAUI
+ *
+ * Description:
+ * ------------
+ * This file contains function prototypes, constants for SSL API.
+ *
+ * Author:
+ * -------
+ * -------
+ *
+ *==============================================================================
+ * HISTORY
+ * Below this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
+ *------------------------------------------------------------------------------
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ * removed!
+ * removed!
+ * removed!
+ *
+ *
+ *------------------------------------------------------------------------------
+ * Upper this line, this part is controlled by PVCS VM. DO NOT MODIFY!!
+ *==============================================================================
+ *******************************************************************************/
+#ifndef _SSL_API_H
+#define _SSL_API_H
+
+#include "ssl_consts.h"
+#include "ssl_enums.h"
+#include "ssl_structs.h"
+#include "ssl_callback.h"
+
+#include "kal_general_types.h"
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_sslv2_client_method
+ * DESCRIPTION
+ * Constructor for the SSLv2 SSL_METHOD structure for a dedicated client.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a client side
+ * SSL context be able to handle SSLv2 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_sslv2_client_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_sslv3_client_method
+ * DESCRIPTION
+ * Constructor for the SSLv3 SSL_METHOD structure for a dedicated client.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a client side
+ * SSL context be able to handle SSLv3 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_sslv3_client_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_tlsv1_client_method
+ * DESCRIPTION
+ * Constructor for the TLSv1 SSL_METHOD structure for a dedicated client.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a client side
+ * SSL context be able to handle TLSv1 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_tlsv1_client_method(void);
+
+#ifdef __OPENSSL_TLS12__
+extern const ssl_method *sec_tlsv1_1_client_method(void);
+
+extern const ssl_method *sec_tlsv1_2_client_method(void);
+#endif
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_sslv23_client_method
+ * DESCRIPTION
+ * Constructor for the SSLv2 and SSLv3 SSL_METHOD structure for a
+ * dedicated client.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a client side
+ * SSL context be able to handle both SSLv2 and SSLv3 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_sslv23_client_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_tlsv1_sslv3_client_method
+ * DESCRIPTION
+ * Constructor for the TLSv1 and SSLv3 SSL_METHOD structure for a
+ * dedicated client.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a client side
+ * SSL context be able to handle both TLSv1 and SSLv3 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_tlsv1_sslv3_client_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_sslv2_server_method
+ * DESCRIPTION
+ * Constructor for the SSLv2 SSL_METHOD structure for a dedicated server.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a server side
+ * SSL context be able to handle SSLv2 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_sslv2_server_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_sslv3_server_method
+ * DESCRIPTION
+ * Constructor for the SSLv3 SSL_METHOD structure for a dedicated server.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a server side
+ * SSL context be able to handle SSLv3 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_sslv3_server_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_tlsv1_server_method
+ * DESCRIPTION
+ * Constructor for the TLSv1 SSL_METHOD structure for a dedicated server.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a server side
+ * SSL context be able to handle TLSv1 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_tlsv1_server_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_sslv23_server_method
+ * DESCRIPTION
+ * Constructor for the SSLv2 and SSLv3 SSL_METHOD structure for a
+ * dedicated server.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a server side
+ * SSL context be able to handle both SSLv2 and SSLv3 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_sslv23_server_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP Protocol Methods>
+ * FUNCTION
+ * sec_tlsv1_sslv3_server_method
+ * DESCRIPTION
+ * Constructor for the TLSv1 and SSLv3 SSL_METHOD structure for a
+ * dedicated server.
+ * PARAMETERS
+ * void.
+ * RETURNS
+ * Constructor as a parameter to sec_ssl_ctx_new() to create a server side
+ * SSL context be able to handle both TLSv1 and SSLv3 messges.
+ * SEE ALSO
+ * sec_ssl_ctx_new
+ *****************************************************************************/
+extern const ssl_method *sec_tlsv1_sslv3_server_method(void);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_new
+ * DESCRIPTION
+ * Crete a new SSL context object as framework for TLS/SSL enabled functions.
+ * PARAMETERS
+ * method : [IN] SSL context constructor such as
+ * sec_sslv3_client_method() or sec_sslv23_client_method(), etc.
+ * RETURNS
+ * If an SSL context is created successfully, a pointer to the created
+ * SSL context is returned. Otherwise, NULL is returned if SSL context
+ * is not created.
+ *****************************************************************************/
+extern ssl_ctx*
+sec_ssl_ctx_new(const ssl_method *method);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_free
+ * DESCRIPTION
+ * Free an allocated SSL context object.
+ * PARAMETERS
+ * ctx : [IN] pointer to SSL context to be freed.
+ * RETURNS
+ * This function returns no diagnostic information.
+ *****************************************************************************/
+extern void sec_ssl_ctx_free(ssl_ctx *ctx);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_prng
+ * DESCRIPTION
+ * Set the pseudo-rnadom-number-generator provider (callback function)
+ * used by the context.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * prng : [IN] Pseudo-number-number-generator provider.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_PTR : No valid pointer.
+ * SEC_ERROR_MEM : Memory allocation failure.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_set_prng(ssl_ctx *ctx, const sec_ssl_prng_generator prng);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_cipher_list
+ * DESCRIPTION
+ * Set list of available SSL ciphersuites.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * ciphers : [IN] List of ciphers.
+ * num : [IN] Number of ciphers in the list.
+ * EXAMPLE
+ * <code>
+ * sec_cipher_enum ciphers[] =
+ * {AES128_SHA, AES256-SHA, RC4_MD5, RC4_SHA, DES_CBC3_SHA};
+ * rc = sec_ssl_ctx_set_cipher_list(*globalCtx,
+ * ciphers,
+ * sizoef(ciphers) / sizoef(sec_cipher_enum));
+ * </code>
+ * RETURN VALUES
+ * 1 : Success.
+ * 0 : Fail.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_set_cipher_list(ssl_ctx *ctx, const sec_cipher_enum ciphers[],
+ const kal_int32 num);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_default_passwd_cb
+ * DESCRIPTION
+ * Set the default password callback called when loading/storing a PEM
+ * certificate with encryption.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context
+ * cb : [IN] Callback function to hand back the password to be used
+ * during decryption.
+ * On invocation, a pointer to 'userdata' is provided.
+ * The callback function must write the password into the
+ * provided buffer 'buf'.
+ * RETURNS
+ * This function returns no diagnostic information.
+ * SEE ALSO
+ * sec_ssl_ctx_set_default_passwd_cb_userdata
+ *****************************************************************************/
+extern void
+sec_ssl_ctx_set_default_passwd_cb(ssl_ctx *ctx, ssl_password_cb cb);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_default_passwd_cb_userdata
+ * DESCRIPTION
+ * Set a pointer to userdata which will be provided to the password callback
+ * on invocation.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * u : [IN] Ask for the password once, then keep it in memory and use
+ * it several times. The password could be stored into the
+ * 'userdata' and pem_passwd_cb() returns the password already
+ * stored.
+ * RETURNS
+ * This function returns no diagnostic information.
+ * SEE ALSO
+ * sec_ssl_ctx_set_default_passwd_cb
+ *****************************************************************************/
+extern void
+sec_ssl_ctx_set_default_passwd_cb_userdata(ssl_ctx *ctx, void *u);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_use_privatekey_file
+ * DESCRIPTION
+ * Adds the first private key found in 'file' to 'ctx'.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * file : [IN] File storing the private key to be loaded.
+ * type : [IN] SEC_SSL_FILETYPE_PEM, or SEC_SSL_FILETYPE_ASN1.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_NULL_PTR : Invalid NULL argument is passed in.
+ * SEC_ERROR_FS : File access error.
+ * otherwise : other internal errors.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_use_privatekey_file(ssl_ctx *ctx, const kal_wchar *file,
+ ssl_filetype_enum type);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_use_certificate_file
+ * DESCRIPTION
+ * Loads the first certificate stored in file into ctx.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * file : [IN] File storing the private key to be loaded.
+ * type : [IN] SEC_SSL_FILETYPE_PEM, or SEC_SSL_FILETYPE_ASN1.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_NULL_PTR : Invalid NULL argument is passed in.
+ * SEC_ERROR_FS : File access error.
+ * otherwise : Other internal errors.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_use_certificate_file(ssl_ctx *ctx, const kal_wchar *file,
+ ssl_filetype_enum type);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_load_verify_locations
+ * DESCRIPTION
+ * Set default locations for trusted CA certificate.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * ca_file : [IN] If ca_file is not NULL, it points to a file of CA
+ * certificates in PEM format. The file can contain several
+ * CA certificates identified by -----BEGIN CERTIFICATE-----
+ * and -----END CERTIFICATE-----.
+ * ca_path : [IN] If ca_path is not NULL, it points to a directory
+ * containing CA certificates in PEM format. The files each
+ * contain one CA certificate. The files are lookedup by the
+ * CA subject name hash value.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_NULL_PTR : Invalid NULL argument is passed in.
+ * SEC_ERROR_FS : File access error.
+ * otherwise : Other internal errors.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_load_verify_locations(ssl_ctx *ctx,
+ const kal_wchar *ca_file,
+ const kal_wchar *ca_path);
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_client_auth_modes
+ * DESCRIPTION
+ * Set client authentication mode.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * modes : [IN] Client authentication modes,
+ * ended with CLIENT_AUTH_MODE_END.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_PTR : No pointer is passed to internal SSL library.
+ * SEC_ERROR_SSL_NEEDS_CIPHER : No client authentication mode is provided.
+ * SEC_ERROR_SSL_BAD_SIDE : Incorrect side for authentication modes.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_set_client_auth_modes(ssl_ctx *ctx,
+ const ssl_auth_mode_enum modes[]);
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_io_funcs
+ * DESCRIPTION
+ * Set I/O functions to the SSL context.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * read_cb : [IN] Read callback to retrieve data to be processed by SSL
+ * library.
+ * write_cb : [IN] Write callback to write SSL library processed data.
+ *
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_NULL_PTR : Passed invalid SSL context argument.
+ * SEC_ERROR_PTR : No pointer is passed to internal SSL library.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_set_io_funcs(ssl_ctx *ctx,
+ const sec_ssl_read_cb read_cb,
+ const sec_ssl_write_cb write_cb);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_alert_func
+ * DESCRIPTION
+ * Set callback function to be invoked while received alert from peer.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * alert_cb : [IN] Application's alert callback to be invoked by SSL library.
+ *
+ * RETURN VALUES
+ * This function returns no diagnostic information.
+ *****************************************************************************/
+extern void
+sec_ssl_ctx_set_alert_func(ssl_ctx *ctx, const sec_ssl_alert_func alert_cb);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_cert_verify_callback
+ * DESCRIPTION
+ * Set certificate verification callback on validating the peer certificate.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * cert_cb : [IN] Read callback to retrieve data to be processed by SSL
+ * library.
+ * arg : [IN] Write callback to write SSL library processed data.
+ * RETURN VALUES
+ * This function returns no diagnostic information.
+ *****************************************************************************/
+extern void
+sec_ssl_ctx_set_cert_verify_callback(ssl_ctx *ctx,
+ const sec_ssl_cert_verify_callback cert_cb,
+ void *arg);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Context APIs>
+ * FUNCTION
+ * sec_ssl_ctx_set_new_ssl_option
+ * DESCRIPTION
+ * Set parameters for creating SSL connection context.
+ *
+ * Because some additional parameters need to be configured before creatig a
+ * connection context from global context, this function has to be called
+ * before calling sec_ssl_new() to set the required options.
+ * PARAMETERS
+ * ctx : [IN] Pointer to SSL context.
+ * def_readbuf_len : [IN] Default size (bytes) of the buffer to read SSL
+ * record, if zero is set to this argument, use
+ * default 4096 bytes.
+ * max_readbuf_len : [IN] Max size (bytes) of the buffer to read SSL record
+ * if zero is set to this argument, use default 32768
+ * bytes.
+ * write_frag_len : [IN] Max size of the data record passed to
+ * sec_ssl_write(). If zero is set to this argument,
+ * use default 4096 bytes.
+ * peer : [IN] For client side applications, this is optional
+ * containing the session key passed to
+ * ssl_GetSessionFunc().
+ * For server side, this contains the session id to be
+ * used for non-resumed sessions.
+ * io_ref : [IN] I/O callback reference.
+ * alert_ref : [IN] Alert callback reference.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : success
+ * SEC_ERROR_NULL_PTR : Passed null SSL context pointer
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ctx_set_new_ssl_option(ssl_ctx *ctx,
+ const kal_uint16 def_readbuf_len,
+ const kal_uint16 max_readbuf_len,
+ const kal_uint16 write_frag_len,
+ const sec_sess_rec peer,
+ void *const io_ref,
+ void *const alert_ref);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_new
+ * DESCRIPTION
+ * Create SSL connection context.
+ * PARAMETERS
+ * ctx : [IN] pointer to SSL connection context.
+ * RETURNS
+ * Return a pointer to allocated SSL connection context on success,
+ * otherwise, return NULL.
+ *****************************************************************************/
+extern ssl_conn* sec_ssl_new(ssl_ctx *ctx);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_free
+ * DESCRIPTION
+ * Free SSL connection context.
+ *
+ * <i> Note: </i>
+ * You should call sec_ssl_shutdown() before calling this function.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURNS
+ * This function returns no diagnostic information.
+ *****************************************************************************/
+extern void sec_ssl_free(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_disable_client_auth
+ * DESCRIPTION
+ * In normal case, if application does not set local identiy and server
+ * sends client authentication request, handshake process will return
+ * SEC_ERROR_LOCAL_IDENTITY_REQUESTED.
+ *
+ * If application would like to proceed without setting client authentication
+ * while receiving client authentication, call this API to skip the check
+ * in the library.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : Success.
+ * 0 : Fail.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_disable_client_auth(ssl_conn *ssl);
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_ocsp_stapling
+ * DESCRIPTION
+ * Set OCSP stapling attributes. Note that this API is only available when
+ * __OCSP_SUPPORT__ is defined.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * use_ocsp : [IN] enable OCSP stapling or not
+ * must_pass : [IN] Must pass OCSP stapling
+ * RETURNS
+ * 1 : Success.
+ * 0 : Fail.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_ocsp_stapling(ssl_conn *ssl, kal_bool use_ocsp, kal_bool must_pass);
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_is_ocsp_stapling_verified
+ * DESCRIPTION
+ * Get the OCSP stapling verification result.
+ * Note that this API is only available when __OCSP_SUPPORT__ is defined.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURNS
+ * KAL_TRUE : Success.
+ * KAL_FALSE : Fail.
+ *****************************************************************************/
+extern kal_bool sec_ssl_is_ocsp_stapling_verified(ssl_conn *ssl);
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_invalidate_session_entry
+ * DESCRIPTION
+ * Invalidate the session cache of the connection
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURNS
+ * void
+ *****************************************************************************/
+extern void sec_ssl_invalidate_session_entry(ssl_conn *ssl);
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_connect
+ * DESCRIPTION
+ * Perform SSL handshake for client side.
+ *
+ * Application should call this API repeatedly until the the return error
+ * code is not WOULD_BLOCK.
+ * On error, call sec_ssl_get_error() to find out the reason.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : The TLS/SSL handshake was successfully complete, a TLS/SSL
+ * connection has been established.
+ * 0 : The TLS/SSL handshake was not successful but was shut down
+ * controlled and by the specifications of the TLS/SSL protocol.
+ * <0 : The TLS/SSL handshake was not successful, because a fatal error
+ * occurred either at the protocol level or a connection failure
+ * occurred. The shutdown was not clean.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_connect(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_accept
+ * DESCRIPTION
+ * Perform SSL handshake for server side.
+ *
+ * Application should call this API repeatedly until the the return error
+ * code is not WOULD_BLOCK.
+ * On error, call sec_ssl_get_error() to find out the reason.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : The TLS/SSL handshake was successfully complete, a TLS/SSL
+ * connection has been established.
+ * 0 : The TLS/SSL handshake was not successful but was shut down
+ * controlled and by the specifications of the TLS/SSL protocol.
+ * <0 : The TLS/SSL handshake was not successful, because a fatal error
+ * occurred either at the protocol level or a connection failure
+ * occurred. The shutdown was not clean.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_accept(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_renegotiate
+ * DESCRIPTION
+ * Requests a renegotiation of the handshake.
+ * Server side: cause data tobe transferred across the connection using the
+ * I/O write callback.
+ * Client side: does not transfer any data.
+ *
+ * After requesting renegotiation, sec_ssl_do_handshake() must be called
+ * to correctly process the renegotiation procedure.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : Success.
+ * 0 : SSL error, call sec_ssl_get_error() to find out the reason.
+ * -1 : Invalid ssl pointer.
+ * SEE ALSO
+ * sec_ssl_do_handshake
+ *****************************************************************************/
+extern kal_int32 sec_ssl_renegotiate(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_do_handshake
+ * DESCRIPTION
+ * Perform SSL rehandshake.
+ *
+ * Application should call this API repeatedly until the the return error
+ * code is not WOULD_BLOCK.
+ * On error, call sec_ssl_get_error() to find out the reason.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : The TLS/SSL handshake was successfully complete, a TLS/SSL
+ * connection has been established.
+ * 0 : The TLS/SSL handshake was not successful but was shut down
+ * controlled and by the specifications of the TLS/SSL protocol.
+ * <0 : The TLS/SSL handshake was not successful, because a fatal error
+ * occurred either at the protocol level or a connection failure
+ * occurred. The shutdown was not clean.
+ * SEE ALSO
+ * sec_ssl_renegotiate
+ *****************************************************************************/
+extern kal_int32 sec_ssl_do_handshake(ssl_conn *ssl);
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_session_reused
+ * DESCRIPTION
+ * To know whether the session is resumed.
+ *
+ * During the negotiation, a client can propose to reuse a session.
+ * The server then looks up the session in its cache. If both client and
+ * server agree on the session, it will be reused and a flag is being set
+ * that can be queried by the application.
+ * PARAMETERS
+ * ssl : [IN] pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : Session is resumed.
+ * 0 : Session is not resumed.
+ * -1 : Error cases, use sec_ssl_get_error() to find out the reason.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_session_reused(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_session_established
+ * DESCRIPTION
+ * To know whether the session is established.
+ * PARAMETERS
+ * ssl : [IN] pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : Session is established.
+ * 0 : Session is not estbalished.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_session_established(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_master_secret
+ * DESCRIPTION
+ * To retrieve the negotiated master secret
+ *
+ * Gets the negotiated master secret for the connection context after
+ * handshake completed, this
+ * PARAMETERS
+ * ssl : [IN] pointer to SSL connection context
+ * secret_buf_len : [IN] size of buffer provided for storing returned P.M.S.
+ * secret : [OUT] pointer to buffer for storing returned P.M.S.
+ * secret_len : [OUT] length of returned P.M.S.
+ * RETURN VALUES
+ * SEC_ERROR_NULL_PTR : NULL SSL context pointer.
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_PTR : NULL pointer was passed to internal library.
+ * SEC_ERROR_BAD_LEN : Secret_buf_len is too small to return secret.
+ * SEC_ERROR_SSL_HSHK_REQUIRED : Handshake must be performed fist.
+ * SEE ALSO
+ * sec_ssl_get_client_random, sec_ssl_get_server_random
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_master_secret(ssl_conn *ssl,
+ kal_uint16 secret_buf_len,
+ kal_uint8 *secret,
+ kal_uint16* secret_len);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_client_random
+ * DESCRIPTION
+ * To retrieve the selected random number by local
+ *
+ * Gets the random field which was encoded in the "client_hello" handshake
+ * message. This function is intended for applications to derive key material
+ * used in EAP-TLS or similar protocols.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * rand_buf_len : [IN] Size of buffer provided for storing returned random.
+ * rand_buf : [OUT] Pointer to buffer for storing returned random.
+ * rand_len : [OUT] Length of returned random.
+ * RETURN VALUES
+ * SEC_ERROR_NULL_PTR : NULL SSL context pointer.
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_PTR : NULL pointer was passed to internal library.
+ * SEC_ERROR_BAD_LEN : Secret_buf_len is too small to return secret.
+ * SEC_ERROR_SSL_HSHK_REQUIRED : Handshake must be performed fist.
+ * SEC_ERROR_SSL_PROTOCOL_VER : Protocol version is smaller than TLS v1.0.
+ * SEE ALSO
+ * sec_ssl_get_server_random, sec_ssl_get_master_secret
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_client_random(ssl_conn *ssl,
+ kal_uint16 rand_buf_len,
+ kal_uint8 *rand_buf,
+ kal_uint16* rand_len);
+
+extern kal_int32
+sec_ssl_get_session_id(ssl_conn *ssl,
+ kal_uint16 session_id_buf_len,
+ kal_uint8 *session_id,
+ kal_uint16 *session_id_len);
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_server_random
+ * DESCRIPTION
+ * To retrieve the selected random number by the remote side
+ *
+ * Gets the random field which was encoded in the "server_hello" handshake
+ * message. This function is intended for applications to derive key material
+ * used in EAP-TLS or similar protocols.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * rand_buf_len : [IN] Size of buffer provided for storing returned random.
+ * rand_buf : [OUT] Pointer to buffer for storing returned random.
+ * rand_len : [OUT] Length of returned random.
+ * RETURN VALUES
+ * SEC_ERROR_NULL_PTR : NULL SSL context pointer.
+ * SEC_ERROR_NONE : Success.
+ * SEC_ERROR_PTR : NULL pointer was passed to internal library.
+ * SEC_ERROR_BAD_LEN : Secret_buf_len is too small to return secret.
+ * SEC_ERROR_SSL_HSHK_REQUIRED : Handshake must be performed fist.
+ * SEC_ERROR_SSL_PROTOCOL_VER : Protocol version is smaller than TLS v1.0.
+ * SEE ALSO
+ * sec_ssl_get_client_random, sec_ssl_get_master_secret
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_server_random(ssl_conn *ssl,
+ kal_uint16 rand_buf_len,
+ kal_uint8 *rand_buf,
+ kal_uint16* rand_len);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_check_peer_cert_cname
+ * DESCRIPTION
+ * To check the Common Name from received peer certificate
+ * PARAMETERS
+ * ssl : [IN] pointer to SSL connection context.
+ * cname : [IN] string of destination srever name,
+ * or set to NULL to disable this function.
+ * RETURN VALUES
+ * SEC_ERROR_NULL_PTR : NULL SSL context pointer.
+ * SEC_ERROR_NONE : Success.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_check_peer_cert_cname(ssl_conn *const ssl, const kal_char *const cname);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_read
+ * DESCRIPTION
+ * Read data from SSL connection.
+ *
+ * sec_ssl_read() works based on the SSL/TLS records. The data are received
+ * in records (with a maximum record size of 16kB for SSLv3/TLSv1).
+ * Only when a record has been completely received, it can be processed
+ * (decryption and check of integrity). Therefore data that was not retrieved
+ * at the last call of sec_ssl_read() can still be buffered inside the SSL
+ * layer and will be retrieved on the next call to sec_ssl_read().
+ * If num is higher than the number of bytes buffered, sec_ssl_read() will
+ * return with the bytes buffered.
+ * PARAMETERS
+ * ssl : [IN] pointer to SSL connection context.
+ * buf : [IN] buffer to put decrypted application data.
+ * num : [IN] size of buf in bytes.
+ * RETURN VALUES
+ * >=0 : Operation successfully, return the bytes actually read from
+ * SSL connection.
+ * -1 : Not successful, error occured or action must be taken by the
+ * calling process, call sec_ssl_get_error() to get the reason.
+ * -2 : Not successful, connection closed.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_read(ssl_conn *ssl, void *buf, kal_int32 num);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_write
+ * DESCRIPTION
+ * Write data to SSL connection.
+ *
+ * sec_ssl_write() will only return with success, when the complete contents
+ * of buf of length num has been written.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context
+ * buf : [IN] Buffer holding application data to be encrypted
+ * num : [IN] Size of buf in bytes
+ * RETURN VALUES
+ * >0 : Operation successfully, return the bytes actually read from
+ * SSL connection.
+ * 0 : Not successful, connection closed.
+ * -1 : Not successful, error occured or action must be taken by the
+ * calling process, call sec_ssl_get_error() to get the reason.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_write(ssl_conn *ssl, const void* buf, kal_int32 num);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_want_read
+ * DESCRIPTION
+ * Probe the staus of the ssl reading buffer.
+ *
+ * There are data in the SSL buffer ready for read to the application buffer.
+ * For socket applications, the encrypted application data might has been
+ * read from socket receiving buffer to SSL read buffer, application can use
+ * this API to probe the SSL buffer state.
+ * PARAMETERS
+ * ssl : [IN] pointer to SSL connection context
+ * RETURN VALUES
+ * 1 : There are data in the SSL buffer to be read for SSL application.
+ * 0 : No data to be read.
+ * -1 : Error occured, call sec_ssl_get_error() to get the reason.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_want_read(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_want_write
+ * DESCRIPTION
+ * Probe the staus of the ssl writing buffer.
+ *
+ * There are data in the SSL buffer that must be written to the underlying
+ * layer in order to complete the actual ssl_*() operation.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : There are data in the SSL buffer to be written to complete the
+ * SSL_* operation.
+ * 0 : No data to be written.
+ * -1 : Error occured, call sec_ssl_get_error() to get the reason.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_want_write(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_shutdown
+ * DESCRIPTION
+ * Shutdown the SSL connection by sending a 'close notify' alert to peer.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * RETURN VALUES
+ * 1 : the SSL shutdown was successfully completed
+ * 0 : the shutdown process is not yet finished, call it one more time.
+ * -1 : shutdown failed because a fatal error occured.
+ *****************************************************************************/
+extern kal_int32 sec_ssl_shutdown(ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_error
+ * DESCRIPTION
+ * Get last SSL error cause.
+ *
+ * sec_ssl_get_error() returns a result code for a preceding call to
+ * ssl_connect(), ssl_accept(), ssl_do_handshake(), ssl_read(), ssl_peek(),
+ * or ssl_write() on ssl. The value returned by that TLS/SSL I/O function
+ * must be passed to sec_ssl_get_error() in parameter ret.
+ * PARAMETERS
+ * ssl : [IN] Pointer to SSL connection context.
+ * ret : [IN] Currently not used.
+ * RETURN VALUES
+ * != : 0 last eror
+ * 0 : Not valid ssl pointer
+ * EXAMPLE
+ * <code>
+ * ret = sec_ssl_connect(ssl_conn);
+ * if (ret != 1)
+ * err = sec_ssl_get_error(ssl_conn, ret);
+ * </code>
+ *****************************************************************************/
+extern kal_int32 sec_ssl_get_error(const ssl_conn *ssl, kal_int32 ret);
+
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_curr_cipher_info
+ * DESCRIPTION
+ * Get the negotiated cipher infomation.
+ * The information contains:
+ * - Protocol version,
+ * - Encryption algorithm,
+ * - Key exchange algorithm,
+ * - Authentication algorithm,
+ * - Hash algorithm.
+ * PARAMETERS
+ * ssl : [IN] Connection context
+ * cipher_info : [OUT] Structure containing the info of negotiated ciphersuite
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success, the cert is copied to buf, with the
+ * length returned from buflen.
+ * SEC_ERROR_NULL_PTR : NULL pointer is passed.
+ * SEC_ERROR_SSL_HSHK_REQUIRED : Handshake must be completed first.
+ * SEC_ERROR_PTR : SSL internal connection context points to
+ * NULL.
+ * SEC_ERROR_BUFFER_SIZE : Given destination buffer is too small, the
+ * required size is returned in the buflen
+ * argument.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_curr_cipher_info(const ssl_conn *ssl,
+ sec_cipher_info_struct *cipher_info);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_cipher_get_version
+ * DESCRIPTION
+ * Get the negotiated SSL/TLS version.
+ * PARAMETERS
+ * ssl : [IN] Connection context
+ * RETURNS
+ * SSL protocol version represented in sec_proto_ver_enum.
+ *****************************************************************************/
+extern sec_proto_ver_enum sec_ssl_cipher_get_version(const ssl_conn *ssl);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_ciphersuite
+ * DESCRIPTION
+ * Get the negotiated ciphersuite.
+ * PARAMETERS
+ * ssl : [IN] Connection context
+ * cipher : [OUT] Returning cipher suite enum of negotiated ciphersuite
+ *
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success, the cert information is extracted.
+ * SEC_ERROR_NULL_PTR : NULL pointer is passed in the argument.
+ * SEC_ERROR_SSL_HSHK_REQUIRED : Handshake must be completed first.
+ * SEC_ERROR_PTR : SSL internal connection context points to
+ * NULL.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_ciphersuite(const ssl_conn *ssl, sec_ciphersuites_enum *cipher);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_peer_certificate
+ * DESCRIPTION
+ * Get the certificate of current session.
+ * PARAMETERS
+ * ssl : [IN] Connection context
+ * cert : [OUT] Buffer to return certificate of current session
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success, the cert information is extracted.
+ * SEC_ERROR_NULL_PTR : NULL pointer is passed in the argument.
+ * SEC_ERROR_SSL_HSHK_REQUIRED : Handshake must be completed first.
+ * SEC_ERROR_PTR : SSL internal connection context points to
+ * NULL.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_peer_certificate(ssl_conn *const ssl, sec_cert_struct *cert);
+
+
+
+/*****************************************************************************
+ * <GROUP SSL Connection APIs>
+ * FUNCTION
+ * sec_ssl_get_certreq_auth_names
+ * DESCRIPTION
+ * The auth name list sent from peer in a client certificate request message.
+ *
+ * For client authentication, the cert types and auth names and used to
+ * filter the local personal certificates meets the criteria to be used as
+ * local identity. If application encountered client authentication during
+ * handshake, it should call this API to extract the information in the
+ * received client authentication request.
+ *
+ * The authentication names in received client authentication request are
+ * returned from the auth_names parameter. The number of received auth names
+ * are returned from auth_name_cnt as output argument. If the total number of
+ * received auth names is larger than input auth_name_cnt, currently SSL
+ * library supports up to 32 client auth names.
+ * PARAMETERS
+ * ssl : [IN] Connection context
+ * cert_types : [OUT] A list of certificate types of certificates
+ * requested, stored in order of the server's
+ * preference.
+ * auth_name_cnt : [IN/OUT] Number of entries in the certificate authorities.
+ * a) As an input argument, which specifies the
+ * size of "auth_names" array.
+ * b) As an output argument, which return the number
+ * of valid entries in the "auht_names" array.
+ * auth_names : [OUT] A list of the distinguished names of acceptable
+ * certificate authorities.
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success, the cert is copied to buf, with the
+ * length returned from buflen.
+ * SEC_ERROR_NULL_PTR : NULL pointer is passed.
+ * SEC_ERROR_PTR : SSL internal connection context points to NULL.
+ * Note that the pointers to auth_names are maintained in SSL wrapper.
+ * The memory holding the data will freed while deleting the connection context.
+ * So, application should be responsible for duplicating the data if necessary.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_get_certreq_auth_names(ssl_conn * ssl,
+ sec_cert_types *cert_types,
+ kal_uint8 *auth_name_cnt,
+ sec_auth_names auth_names[]);
+
+
+
+/*****************************************************************************
+ * <GROUP Utility Functions>
+ * FUNCTION
+ * sec_ssl_extract_cert
+ * DESCRIPTION
+ * Extract the certificate in cert to user buffer.
+ *
+ * For applications would like to extract a certificate stored in
+ * sec_cert structure to user buffer. Application should provide a buffer
+ * to store the extracted certificate. For the first time, application does
+ * not know the required buffer to extract the certificate, application can
+ * pass an NULL buffer and check the value in buf_len to allocate a block of
+ * memory with sufficient size.
+ * PARAMETERS
+ * cert : [IN] Source structure holding certificate to be extracted
+ * buf : [IN] Buffer provided by user to hold the copied cert
+ * buflen : [IN] Length of the given buffer, a argument for both
+ * input and output.
+ * 1. For input, it specifies the size of buffer provided
+ * by user
+ * 2. For ouptut:
+ * a) in error of insufficient size, it returns the
+ * required size for extracting the certificate
+ * b) in success case, it contains the size of the
+ * extracted certificate
+ * RETURN VALUES
+ * SEC_ERROR_NONE : Success, the cert is copied to buf, with the
+ * length returned from buflen.
+ * SEC_ERROR_NULL_PTR : NULL pointer is passed.
+ * SEC_ERROR_PTR : SSL internal connection context points to NULL.
+ * SEC_ERROR_BUFFER_SIZE : given destination buffer is too small, the required
+ * size is returned in the buflen argument.
+ *****************************************************************************/
+extern kal_int32
+sec_ssl_extract_cert(const sec_cert_struct *cert, kal_uint8 *buf, kal_uint32 *buflen);
+
+
+
+/*****************************************************************************
+ * <GROUP Utility Functions>
+ * FUNCTION
+ * sec_ssl_log_plaintext
+ * DESCRIPTION
+ * Enable/disable plaintext logging mechanism, default if off.
+ *
+ * This API is used designed for debugging SSL/TLS applications.
+ * Because all applications over SSL/TLS send and receive encrypted data in
+ * the network, application can invoke this API to turn on the logging
+ * mechanism to check the plaintext content in the application layer.
+ *
+ * For security consideration, This API will only be effective when the
+ * global compile __PRODUCTION_RELEASE__ is not defined.
+ *
+ * As long as this API is invoked to turn on the logging mechanism, all data
+ * flow over SSL/TLS in the system will be logged.
+ *
+ * The message will be logged as MSG_ID_APP_SSL_DATA_INPUT_MSG and
+ * MSG_ID_APP_SSL_DATA_OUTPUT_MSG to MOD_SOC.
+ *
+ * Note:
+ * 1. The ILMs only be sent when a successful SSL read()/write() is invoked.
+ * 2. The ret field in the message is the number of data been read/write.
+ * 3. The len field in the message is the peer buffer allocated for
+ * sending/recving data, if the buffer called in the API is too large
+ * (> 2048-peer_buff_struct), multiple messages will be sent in the log
+ * 4. The mf field in the message indicates whether there are more fragments
+ * for this read/write operation
+ *
+ * PARAMETERS
+ * onoff : [IN] Switch on/off the plaintext logging mechanism.
+ * RETURNS
+ * This function returns no diagnostic information.
+ *****************************************************************************/
+extern void sec_ssl_log_plaintext(const kal_bool onoff);
+
+
+
+/*****************************************************************************
+ * <GROUP Utility Functions>
+ * FUNCTION
+ * sec_ssl_clear_library_error
+ * DESCRIPTION
+ * Clear library error variable.
+ * PARAMETERS
+ * void
+ * RETURNS
+ * This function returns no diagnostic information.
+ *****************************************************************************/
+extern void sec_ssl_clear_library_error(void);
+
+extern void sec_ssl_init_conn_method (ssl_ctx *ctx, ssl_conn *s_conn);
+extern void sec_ssl_set_cert_validate_status (kal_bool status, ssl_conn *s_conn);
+extern kal_int32 sec_ssl_set_host_name(ssl_conn *s, kal_char *host);
+#endif /* !_SSL_API_H */
+
+