 |
API Description
At first the library must be initialized; see SSL_library_init(). Then an SSL_CTX object is created as a framework to establish TLS/SSL enabled connections (see SSL_CTX_new). Various options regarding certificates, algorithms etc. can be set in this object. When a network connection has been created, it can be assigned to an SSL object. After the SSL object has been created using SSL_new, SSL_set_fd or SSL_set_bio can be used to associate the network connection with the object. Then the TLS/SSL handshake is performed using SSL_accept or SSL_connect respectively. SSL_read and SSL_write are used to read and write data on the TLS/SSL connection. SSL_shutdown can be used to shut down the TLS/SSL connection. The libssl library is arranged into following categories:
Note: Some of the SSL functions need more than the default available stack. The recommended stack size is 10K. To set the stack size to 10K add EPOCSTACKSIZE 0x10000 in the MMP file.
|
API Categories
The application or project that intends to use OPEN SSL must mention the paths as shown below:
SYSTEMINCLUDE \epoc32\include\stdapis SYSTEMINCLUDE \epoc32\include\stdapis\openssl
Currently the ssl library exports 202 API functions. They are documented in the following:
|
Dealing with Protocol Methods
Documented here are the various API functions which deal with the SSL/TLS protocol methods defined in SSL_METHOD structures.
Dealing with Protocol Methods
Function |
Description |
| SSLv2_client_method | Constructor for the SSLv2 SSL_METHOD structure for a dedicated client. |
| SSLv2_server_method | Constructor for the SSLv2 SSL_METHOD structure for a dedicated server. |
| SSLv2_method | Constructor for the SSLv2 SSL_METHOD structure for combined client and server. |
| SSLv3_client_method | Constructor for the SSLv3 SSL_METHOD structure for a dedicated client. |
| SSLv3_server_method | Constructor for the SSLv3 SSL_METHOD structure for a dedicated server. |
| SSLv3_method | Constructor for the SSLv3 SSL_METHOD structure for combined client and server. |
| TLSv1_client_method | Constructor for the TLSv1 SSL_METHOD structure for a dedicated client. |
| TLSv1_server_method | Constructor for the TLSv1 SSL_METHOD structure for a dedicated server. |
| TLSv1_method | Constructor for the TLSv1 SSL_METHOD structure for combined client and server. |
| DTLSv1_method | Constructor for the DTLSv1 SSL_METHOD structure for combined client and server. |
| DTLSv1_server_method | Constructor for the DTLSv1 SSL_METHOD structure for a dedicated server. |
| DTLSv1_client_method | Constructor for the DTLSv1 SSL_METHOD structure for a dedicated client. |
|
Dealing with Ciphers
Dealing with Ciphers
Documented here are the various API functions which deal with the SSL/TLS ciphers defined in SSL_CIPHER structures.
Function |
Description |
| SSL_CIPHER_description, SSL_CIPHER_get_bits, SSL_CIPHER_get_name, SSL_CIPHER_get_version | Gets SSL_CIPHER properties. |
|
Dealing with Protocol Contexts
Dealing with Protocol Contexts
Documented here are the various API functions which deal with the SSL/TLS protocol context defined in the SSL_CTX structure.
Function |
Description |
| SSL_CTX_add_client_CA, SSL_CTX_set_client_CA_list | Sets list of CAs sent to the client when requesting a client certificate. |
| SSL_CTX_add_extra_chain_cert | Adds certificate to chain. |
| SSL_CTX_add_session, SSL_CTX_remove_session | Manipulats session cache. |
| SSL_CTX_check_private_key, SSL_CTX_use_PrivateKey, SSL_CTX_use_PrivateKey_ASN1, SSL_CTX_use_PrivateKey_file, SSL_CTX_use_RSAPrivateKey, SSL_CTX_use_RSAPrivateKey_ASN1, SSL_CTX_use_RSAPrivateKey_file, SSL_CTX_use_certificate, SSL_CTX_use_certificate_ASN1, SSL_CTX_use_certificate_file | Loads certificate and key data. |
| SSL_CTX_ctrl | Internal handling functions for SSL_CTX and SSL objects. |
| SSL_CTX_flush_sessions | Removes expired sessions. |
| SSL_CTX_free | Frees an allocated SSL_CTX object. |
| SSL_CTX_get_app_data, SSL_CTX_set_app_data | |
| SSL_CTX_get_cert_store, SSL_CTX_set_cert_store | Manipulates X509 certificate verification storage. |
| SSL_CTX_get_client_CA_list | Gets list of client CAs. |
| SSL_CTX_get_client_cert_cb | Handles client certificate callback function. |
| SSL_CTX_get_ex_data, SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data | Internal application specific data functions |
| SSL_CTX_get_info_callback | Handles information callback for SSL connections. |
| SSL_CTX_get_quiet_shutdown | manipulates shutdown behaviour. |
| SSL_CTX_get_session_cache_mode | enable/disable session caching. |
| SSL_CTX_get_timeout, SSL_CTX_set_timeout | Manipulates timeout values for session caching |
| SSL_CTX_get_verify_callback, SSL_CTX_get_verify_mode | Gets currently set verification parameters. |
| SSL_CTX_load_verify_locations | Sets default locations for trusted CA certificates. |
| SSL_CTX_need_tmp_rsa | Handles RSA keys for ephemeral key exchange. |
| SSL_CTX_new | creates a new SSL_CTX object as framework for TLS/SSL enabled functions |
| SSL_CTX_sess_accept, SSL_CTX_sess_accept_good, SSL_CTX_sess_accept_renegotiate, SSL_CTX_sess_cache_full, SSL_CTX_sess_cb_hits, SSL_CTX_sess_connect, SSL_CTX_sess_connect_good, SSL_CTX_sess_connect_renegotiate, SSL_CTX_sess_hits, SSL_CTX_sess_misses, SSL_CTX_sess_number, SSL_CTX_sess_timeouts | Obtain session cache statistics. |
| SSL_CTX_sess_get_cache_size, SSL_CTX_sess_set_cache_size | Manipulates session cache size. |
| SSL_CTX_sess_get_get_cb, SSL_CTX_sess_get_new_cb, SSL_CTX_sess_get_remove_cb, SSL_CTX_sess_set_get_cb, SSL_CTX_sess_set_new_cb, SSL_CTX_sess_set_remove_cb | provides callback functions for server side external session caching. |
| SSL_CTX_sessions | access internal session cache. |
| SSL_CTX_set_cipher_list | chooses list of available SSL_CIPHERs. |
| SSL_CTX_set_client_cert_cb | Handles client certificate callback function. |
| SSL_CTX_set_default_passwd_cb | Sets passwd callback for encrypted PEM file handling. |
| SSL_CTX_set_default_read_ahead | |
| SSL_CTX_set_default_verify_paths | |
| SSL_CTX_set_info_callback | Handles information callback for SSL connections. |
| SSL_CTX_set_msg_callback, SSL_CTX_set_msg_callback_arg | install callback for observing protocol . |
| SSL_CTX_set_options | Manipulates SSL engine options. |
| SSL_CTX_set_quiet_shutdown | Manipulates shutdown behaviour. |
| SSL_CTX_set_session_cache_mode | enable/disable session caching. |
| SSL_CTX_set_ssl_version | chooses a new TLS/SSL method |
| SSL_CTX_set_tmp_dh, SSL_CTX_set_tmp_dh_callback | Handles DH keys for ephemeral key exchange. |
| SSL_CTX_set_tmp_rsa, SSL_CTX_set_tmp_rsa_callback, SSL_set_tmp_rsa_callback | Handles RSA keys for ephemeral key exchange. |
| SSL_CTX_set_verify | Sets peer certificate verification parameters. |
| SSL_CTX_callback_ctrl | Internal handling function for SSL_CTX and SSL objects. |
| SSL_CTXget_verify_depth, SSL_get_verify_depth | Gets currently set verification parameters. |
| SSL_CTX_set_cert_verify_callback | Sets peer certificate verification procedure. |
| SSL_CTX_set_default_passwd_cb_userdata | Sets passwd callback for encrypted PEM file handling. |
| SSL_CTX_set_verify_depth, SSL_set_verify_depth | Sets peer certificate verification parameters. |
| SSL_CTX_use_certificate_chain_file | Loads certificate and key data. |
| SSL_CTX_set_session_id_context | Sets context within which session can be reused (server side only). |
| SSL_CTX_set_generate_session_id | Manipulate generation of SSL session IDs (server only). |
| SSL_CTX_need_tmp_rsa | Handles RSA keys for ephemeral key exchange. |
| SSL_CTX_get_options | Manipulates SSL engine options. |
| SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list | Manipulate allowed for the peer's certificate chain. |
| SSL_CTX_set_mode, SSL_CTX_get_mode | Manipulate SSL engine mode. |
|
Dealing with Sessions
Dealing with Sessions
Documented here are the various API functions which deal with the SSL/TLS sessions defined in the SSL_SESSION structures.
Function |
Description |
| d2i_SSL_SESSION, i2d_SSL_SESSION | Transforms the external ASN1 representation of an SSL/TLS session, stored as binary data at location pp with length length, into an SSL_SESSION object. |
| SSL_SESSION_cmp | |
| SSL_SESSION_free | Frees an allocated SSL_SESSION structure. |
| SSL_SESSION_get_app_data | |
| SSL_SESSION_get_ex_data, SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data | Internal application specific data functions. |
| SSL_SESSION_get_time, SSL_SESSION_get_timeout, SSL_SESSION_set_time, SSL_SESSION_set_timeout | Retrieves and manipulates session time and timeout settings. |
| SSL_SESSION_hash | |
| SSL_SESSION_new | |
| SSL_SESSION_print | |
| SSL_SESSION_print_fp | |
| SSL_SESSION_set_app_data |
|
Dealing with Connections
Dealing with Connections
Documented here are the various API functions which deal with the SSL/TLS connection defined in the SSL structure.
Function |
Description |
| SSL_accept | Waits for a TLS/SSL client to initiate the TLS/SSL handshake. |
| SSL_add_dir_cert_subjects_to_stack | |
| SSL_add_file_cert_subjects_to_stack | |
| SSL_add_client_CA | Sets list of CAs sent to the client when requesting a client certificate. |
| SSL_alert_desc_string, SSL_alert_desc_string_long, SSL_alert_type_string, SSL_alert_type_string_long | Gets textual description of alert information. |
| SSL_check_private_key | Loads certificate and key data. |
| SSL_clear | Resets ssl to allow another connection. |
| SSL_clear_num_renegotiations | |
| SSL_connect | Initiates the TLS/SSL handshake with an TLS/SSL server. |
| SSL_copy_session_id | |
| SSL_ctrl | Internal handling functions for SSL_CTX and SSL objects |
| SSL_do_handshake | Performs a TLS/SSL handshake. |
| SSL_dup, SSL_dup_CA_list | |
| SSL_free | Frees an allocated SSL structure. |
| SSL_get_SSL_CTX | Gets the SSL_CTX from which an SSL is created. |
| SSL_get_app_data | |
| SSL_get_certificate | |
| SSL_get_cipher_list, SSL_get_ciphers | Gets list of available SSL_CIPHERs. |
| SSL_get_cipher_bits,SSL_get_cipher_name, SSL_get_cipher_version, SSL_get_cipher, SSL_get_current_cipher | Gets SSL_CIPHER of a connection. |
| SSL_get_client_CA_list | Gets list of client CAs. |
| SSL_get_default_timeout | Gets default session time-out value. |
| SSL_get_error | Obtains result code for TLS/SSL I/O operation. |
| SSL_get_ex_data_X509_STORE_CTX_idx | Gets ex_data index to access SSL structure from X509_STORE_CTX. |
| SSL_get_ex_new_index, SSL_get_ex_data | internal application specific data functions. |
| SSL_get_fd | Get file descriptor linked to an SSL object. |
| SSL_get_info_callback, SSL_set_info_callback | Handles information callback for SSL connections. |
| SSL_get_peer_cert_chain | Gets the X509 certificate chain of the peer. |
| SSL_get_peer_certificate | Gets the X509 certificate of the peer. |
| SSL_get_privatekey | |
| SSL_get_quiet_shutdown, SSL_set_quiet_shutdown | Manipulates shutdown behaviour. |
| SSL_get_rbio | Gets BIO linked to an SSL object. |
| SSL_get_read_ahead | |
| SSL_get_session | Retrieves TLS/SSL session data. |
| SSL_get_shared_ciphers | |
| SSL_get_shutdown, SSL_set_shutdown | Manipulates shutdown state of an SSL connection. |
| SSL_get_ssl_method | Chooses a new TLS/SSL method. |
| SSL_get_state | |
| SSL_get_time, SSL_get_timeout | Retrieves and manipulates session time and timeout settings. |
| SSL_get_verify_callback, SSL_get_verify_mode | Gets currently set verification parameters. |
| SSL_get_verify_result | Gets result of peer certificate verification. |
| SSL_get_version | Gets the protocol version of a connection. |
| SSL_get_wbio | Gets BIO linked to an SSL object. |
| SSL_in_accept_init, SSL_in_connect_init, SSL_in_init, SSL_is_init_finished | |
| SSL_in_before | |
| SSL_load_client_CA_file | Loads certificate names from file. |
| SSL_load_error_strings | |
| SSL_new | Creates a new SSL structure for a connection. |
| SSL_num_renegotiations, SSL_renegotiate | |
| SSL_peek | |
| SSL_pending | Obtain number of readable bytes buffered in an SSL object. |
| SSL_read | Reads bytes from a TLS/SSL connection. |
| SSL_rstate_string, SSL_rstate_string_long | Gets textual description of state of an SSL object during read operation. |
| SSL_session_reused | Queries whether a reused session was negotiated during handshake. |
| SSL_set_accept_state | Prepares SSL object to work in client or server mode. |
| SSL_set_app_data | |
| SSL_set_bio | Connects the SSL object with a BIO. |
| SSL_set_cipher_list | Chooses list of available SSL_CIPHERs. |
| SSL_set_client_CA_list | Sets list of CAs sent to the client when requesting a client certificate. |
| SSL_set_connect_state | Prepares SSL object to work in client or server mode. |
| SSL_set_ex_data | Internal application specific data functions. |
| SSL_set_fd | Connects the SSL object with a file descriptor. |
| SSL_set_msg_callback, SSL_set_msg_callback_arg | Installs callback for observing protocol . |
| SSL_set_options | Manipulates SSL engine options. |
| SSL_set_read_ahead | |
| SSL_set_rfd | Connects the SSL object with a read channel file descriptor. |
| SSL_set_session | Sets a TLS/SSL session to be used during TLS/SSL connect. |
| SSL_set_ssl_method | Chooses a new TLS/SSL method. |
| SSL_set_time, SSL_set_timeout | Retrieve and manipulate session time and timeout settings. |
| SSL_set_verify | Sets peer certificate verification parameters |
| SSL_set_verify_result | Overrides result of peer certificate verification. |
| SSL_set_wfd | Connects the SSL object with a read channel file descriptor. |
| SSL_shutdown | Shuts down a TLS/SSL connection. |
| SSL_state | |
| SSL_state_string, SSL_state_string_long | Gets textual description of state of an SSL object. |
| SSL_total_renegotiations | |
| SSL_use_PrivateKey, SSL_use_PrivateKey_ASN1, SSL_use_PrivateKey_file,SSL_use_RSAPrivateKey, SSL_use_RSAPrivateKey_ASN1, SSL_use_RSAPrivateKey_file, SSL_use_certificate, SSL_use_certificate_ASN1, SSL_use_certificate_file | Loads certificate and key data. |
| SSL_version | |
| SSL_want,SSL_want_nothing, SSL_want_read, SSL_want_write,SSL_want_x509_lookup | Obtains state information TLS/SSL I/O operation. |
| SSL_write | Writes num bytes from the buffer buf into the specified ssl connection. |
| SSL_set_session_id_context | Sets context within which session can be reused (server side only). |
|
General Functions
Function |
Description |
| SSL_COMP_add_compression_method, SSL_add_session, SSL_remove_session | Handles SSL/TLS integrated compression methods. |
| SSL_callback_ctrl | Internal handling functions for SSL_CTX and SSL objects. |
| SSL_flush_sessions | Removes expired sessions. |
| SSL_set_generate_session_id, SSL_has_matching_session_id | Manipulates generation of SSL session IDs (server only.) |
| SSL_set_max_cert_list,SSL_get_max_cert_list | Manipulates allowed for the peer's certificate chain. |
| SSL_set_mode, SSL_get_mode | Manipulates SSL engine mode. |
| SSL_get_msg_callback_arg | Installs callback for observing protocol. |
| SSL_get_options | Manipulates SSL engine options. |
| SSL_set_tmp_dh_callback, SSL_set_tmp_dh | Handles DH keys for ephemeral key exchange. |
| SSL_set_tmp_rsa, SSL_need_tmp_rsa | Handles RSA keys for ephemeral key exchange. |
| SSL_library_init,OpenSSL_add_ssl_algorithms, SSLeay_add_ssl_algorithms | Initializes SSL library by registering algorithms. |