Ecore Connection SSL Functions

Functions
Ecore Connection SSL Functions
Ecore » Ecore_Con - Connection functions

Functions that operate on Ecore connection objects pertaining to SSL. More...

## Functions
ECORE_CON_API int | ecore_con_ssl_available_get (void)
| Returns if SSL support is available. More...
ECORE_CON_API Eina_Bool | ecore_con_ssl_server_cert_add (Ecore_Con_Server *svr, const char *cert)
| Adds an SSL certificate for use in ecore_con functions. More...
ECORE_CON_API Eina_Bool | ecore_con_ssl_server_privkey_add (Ecore_Con_Server *svr, const char *key_file)
| Adds an SSL private key for use in ecore_con functions. More...
ECORE_CON_API Eina_Bool | ecore_con_ssl_server_crl_add (Ecore_Con_Server *svr, const char *crl_file)
| Adds an SSL CRL for use in ecore_con functions. More...
ECORE_CON_API Eina_Bool | ecore_con_ssl_server_cafile_add (Ecore_Con_Server *svr, const char *ca_file)
| Adds an SSL CA file for use in ecore_con functions. More...
ECORE_CON_API void | ecore_con_ssl_server_verify (Ecore_Con_Server *svr)
| Enables certificate verification on a server object. More...
ECORE_CON_API void | ecore_con_ssl_server_verify_basic (Ecore_Con_Server *svr)
| Enables hostname-based certificate verification on a server object. More...
ECORE_CON_API void | ecore_con_ssl_server_verify_name_set (Ecore_Con_Server *svr, const char *name)
| Sets the hostname to verify against in certificate verification. More...
ECORE_CON_API const char * | ecore_con_ssl_server_verify_name_get (Ecore_Con_Server *svr)
| Gets the hostname to verify against in certificate verification. More...
ECORE_CON_API Eina_Bool | ecore_con_ssl_server_upgrade (Ecore_Con_Server *svr, Ecore_Con_Type ssl_type)
| Upgrades a connection to a specified level of encryption. More...
ECORE_CON_API Eina_Bool | ecore_con_ssl_client_upgrade (Ecore_Con_Client *cl, Ecore_Con_Type ssl_type)
| Upgrades a connection to a specified level of encryption. More...

## Detailed Description

Functions that operate on Ecore connection objects pertaining to SSL.

## Function Documentation

## ◆ ecore_con_ssl_available_get()

ECORE_CON_API int ecore_con_ssl_available_get | ( | void |  | ) |

Returns if SSL support is available.

Returns
  `1` if SSL is available and provided by gnutls, `2` if SSL is available and provided by openssl, `0` if it is not available.

Referenced by ecore_ipc_ssl_available_get().

## ◆ ecore_con_ssl_server_cert_add()

ECORE_CON_API Eina_Bool ecore_con_ssl_server_cert_add | ( | Ecore_Con_Server * | svr,
|  | const char * | cert
| ) |  |

Adds an SSL certificate for use in ecore_con functions.

Use this function to add a SSL PEM certificate. Simply specify the cert here to use it in the server object for connecting or listening. If there is an error loading the certificate, an error will automatically be logged.

Parameters

  svr | The server object
  cert | The path to the certificate.

Returns
  `EINA_FALSE` if the file cannot be loaded, otherwise `EINA_TRUE`.

Examples
  ecore_con_server_example.c.

References EINA_FALSE, eina_list_append(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, eina_stringshare_add(), and EINA_TRUE.

## ◆ ecore_con_ssl_server_privkey_add()

ECORE_CON_API Eina_Bool ecore_con_ssl_server_privkey_add | ( | Ecore_Con_Server * | svr,
|  | const char * | key_file
| ) |  |

Adds an SSL private key for use in ecore_con functions.

Use this function to add a SSL PEM private key. Simply specify the key file here to use it in the server object for connecting or listening. If there is an error loading the key, an error will automatically be logged.

Parameters

  svr | The server object.
  key_file | The path to the key file.

Returns
  `EINA_FALSE` if the file cannot be loaded, otherwise `EINA_TRUE`.

Examples
  ecore_con_server_example.c.

References EINA_FALSE, eina_list_append(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, eina_stringshare_add(), and EINA_TRUE.

## ◆ ecore_con_ssl_server_crl_add()

ECORE_CON_API Eina_Bool ecore_con_ssl_server_crl_add | ( | Ecore_Con_Server * | svr,
|  | const char * | crl_file
| ) |  |

Adds an SSL CRL for use in ecore_con functions.

Use this function to add a SSL PEM CRL file. Simply specify the CRL file here to use it in the server object for connecting or listening. If there is an error loading the CRL, an error will automatically be logged.

Parameters

  svr | The server object.
  crl_file | The path to the CRL file.

Returns
  `EINA_FALSE` if the file cannot be loaded, otherwise `EINA_TRUE`.

References EINA_FALSE, eina_list_append(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, eina_stringshare_add(), and EINA_TRUE.

## ◆ ecore_con_ssl_server_cafile_add()

ECORE_CON_API Eina_Bool ecore_con_ssl_server_cafile_add | ( | Ecore_Con_Server * | svr,
|  | const char * | ca_file
| ) |  |

Adds an SSL CA file for use in ecore_con functions.

Use this function to add a SSL PEM CA file. Simply specify the file here to use it in the server object for connecting or listening. If there is an error loading the CAs, an error will automatically be logged.

Parameters

  svr | The server object.
  ca_file | The path to the CA file.

Returns
  `EINA_FALSE` if the file cannot be loaded, otherwise `EINA_TRUE`.

Note
  since 1.2, this function can load directories.

Examples
  ecore_con_client_example.c.

References EINA_FALSE, eina_list_append(), EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, eina_stringshare_add(), and EINA_TRUE.

## ◆ ecore_con_ssl_server_verify()

ECORE_CON_API void ecore_con_ssl_server_verify | ( | Ecore_Con_Server * | svr | ) |

Enables certificate verification on a server object.

Call this function on a server object before main loop has started to enable verification of certificates against loaded certificates.

Parameters

  svr | The server object

Examples
  ecore_con_client_example.c.

References EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, EINA_TRUE, and WRN.

## ◆ ecore_con_ssl_server_verify_basic()

ECORE_CON_API void ecore_con_ssl_server_verify_basic | ( | Ecore_Con_Server * | svr | ) |

Enables hostname-based certificate verification on a server object.

Call this function on a server object before main loop has started to enable verification of certificates using ONLY their hostnames.

Parameters

  svr | The server object.

Note
  This function has no effect when used on a listening server created by ecore_con_server_add.

Since
  1.1

Examples
  ecore_con_client_example.c.

References EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, EINA_TRUE, and WRN.

## ◆ ecore_con_ssl_server_verify_name_set()

ECORE_CON_API void ecore_con_ssl_server_verify_name_set | ( | Ecore_Con_Server * | svr,
|  | const char * | name
| ) |  |

Sets the hostname to verify against in certificate verification.

Sometimes the certificate hostname will not match the hostname that you are connecting to, and will instead match a different name. An example of this is that if you connect to talk.google.com to use Google Talk, you receive Google's certificate for gmail.com. This certificate should be trusted, and so you must call this function with "gmail.com" as `name`. See RFC2818 for more details.

Parameters

  svr | The server object.
  name | The hostname to verify against

Since
  1.2

References EINA_SAFETY_ON_NULL_RETURN, EINA_SAFETY_ON_TRUE_RETURN, and eina_stringshare_replace().

## ◆ ecore_con_ssl_server_verify_name_get()

ECORE_CON_API const char* ecore_con_ssl_server_verify_name_get | ( | Ecore_Con_Server * | svr | ) |

Gets the hostname to verify against in certificate verification.

This function returns the name which will be used to validate the SSL certificate common name (CN) or alt name (subjectAltName). It will default to the `name` param in ecore_con_server_connect(), but can be changed with ecore_con_ssl_server_verify_name_set().

Parameters

  svr | The server object.

Returns
  The hostname which will be used

Since
  1.2

## ◆ ecore_con_ssl_server_upgrade()

ECORE_CON_API Eina_Bool ecore_con_ssl_server_upgrade | ( | Ecore_Con_Server * | svr,
|  | Ecore_Con_Type | ssl_type
| ) |  |

Upgrades a connection to a specified level of encryption.

Use this function to begin an SSL handshake on a connection (STARTTLS or similar). Once the upgrade has been completed, an ECORE_CON_EVENT_SERVER_UPGRADE event will be emitted. The connection should be treated as disconnected until the next event.

Parameters

  svr | The server object.
  ssl_type | The SSL connection type (ONLY).

Returns
  `EINA_FALSE` if the connection cannot be upgraded, otherwise `EINA_TRUE`.

Note
  This function is NEVER to be used on a server object created with ecore_con_server_add.

Warning
  Setting a wrong value for `ssl_type` WILL mess up your program.

Since
  1.1

Examples
  ecore_con_client_example.c.

References ecore_animator_frametime_get(), ecore_con_server_flush(), ecore_time_get(), EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, EINA_TRUE, and ERR.

## ◆ ecore_con_ssl_client_upgrade()

ECORE_CON_API Eina_Bool ecore_con_ssl_client_upgrade | ( | Ecore_Con_Client * | cl,
|  | Ecore_Con_Type | ssl_type
| ) |  |

Upgrades a connection to a specified level of encryption.

Use this function to begin an SSL handshake on a connection (STARTTLS or similar). Once the upgrade has been completed, an ECORE_CON_EVENT_CLIENT_UPGRADE event will be emitted. The connection should be treated as disconnected until the next event.

Parameters

  cl | The client object.
  ssl_type | The SSL connection type (ONLY).

Returns
  `EINA_FALSE` if the connection cannot be upgraded, otherwise `EINA_TRUE`.

Warning
  Setting a wrong value for `ssl_type` WILL mess up your program.

Since
  1.1

Examples
  ecore_con_server_example.c.

References ecore_animator_frametime_get(), ecore_con_client_flush(), ecore_time_get(), EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, and ERR.