 |
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:
|
|
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
Here we document 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. |
|
|
Dealing with Ciphers
Dealing with Ciphers
Here we document 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
Here we document 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
Here we document 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
Here we document 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. |