Genivia - SSL/TLS context and functions

|  | Home | Documentation | SSL/TLS context and functions updated Mon Apr 22 2024 by Robert van Engelen |

- Main Page
- Modules
- Classes
- Files

Macros | Typedefs | Functions
SSL/TLS context and functions

This module defines functions to set the SSL/TLS context for HTTPS and WS-Security. More...

## Macros
#define | SOAP_SSL_DEFAULT (SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION | SOAP_TLSv1)
| `soap_ssl_flags` flag with `SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION` and `SOAP_TLSv1` enabled by default More...
#define | SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE
| `soap_ssl_flags` flag value to allow self-signed and expired certificates and those without CRL to be used for authentication More...
#define | SOAP_SSL_NO_AUTHENTICATION
| `soap_ssl_flags` flag value to disable authentication of the peer More...
#define | SOAP_SSL_NO_DEFAULT_CA_PATH
| `soap_ssl_flags` flag value to prevent OpenSSL from calling `SSL_CTX_set_default_verify_paths` More...
#define | SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION
| `soap_ssl_flags` flag for servers to require clients to authenticate to servers during the HTTPS handshake More...
#define | SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION
| `soap_ssl_flags` flag for clients to require servers to authenticate to clients during the HTTPS handshake More...
#define | SOAP_SSL_RSA
| `soap_ssl_flags` flag value to use RSA instead of DH (automatically set when no DH parameter is specified) More...
#define | SOAP_SSL_SKIP_HOST_CHECK
| `soap_ssl_flags` flag for clients to allow clients to skip common name checks against the host name of the server More...
#define | SOAP_SSL_SNI_HOST_CHECK
| `soap_ssl_flags` flag for clients to perform SNI only when the host address is a syntactically valid hostname, not an IP address More...
#define | SOAP_SSLv3
| `soap_ssl_flags` flag value to enable SSL v3 but disable TLS, should be used for legacy purposes only More...
#define | SOAP_SSLv3_TLSv1
| `soap_ssl_flags` flag value to enable both SSL v3 and TLS 1 (TLS 1.0 to max) More...
#define | SOAP_TLSv1
| `soap_ssl_flags` flag value to enable TLS v1 (TLS 1.0 and higher) and to disable SSL v3 More...
#define | SOAP_TLSv1_0
| `soap_ssl_flags` flag value to enable TLS 1.0 More...
#define | SOAP_TLSv1_1
| `soap_ssl_flags` flag value to enable TLS 1.1 More...
#define | SOAP_TLSv1_2
| `soap_ssl_flags` flag value to enable TLS 1.2 More...
#define | SOAP_TLSv1_3
| `soap_ssl_flags` flag value to enable TLS 1.3 More...

## Typedefs
typedef unsigned short | soap_ssl_flags
| SSL/TLS (HTTPS) client and server context flags for `soap_ssl_client_context` and `soap_ssl_server_context`, respectively, flags can be combined with `|` (bit-wise or) More...

## Functions
void | soap_ssl_init (void)
| Initialize the SSL/TLS library. More...
void | soap_ssl_noinit (void)
| Do not initalized the SSL/TLS library. More...
int | soap_ssl_server_context (struct soap *soap, soap_ssl_flags flags, const char *keyfile, const char *password, const char *cafile, const char *capath, const char *dhfile, const char *randfile, const char *sid)
| Initialize the server-side SSL/TLS context. More...
int | soap_ssl_client_context (struct soap *soap, soap_ssl_flags flags, const char *keyfile, const char *password, const char *cafile, const char *capath, const char *randfile)
| Initialize the client-side SSL/TLS context. More...
int | soap_ssl_crl (struct soap *soap, const char *crlfile)
| Enable SSL/TLS CRLs. More...
int | soap_ssl_accept (struct soap *soap)
| Accept SSL/TLS connection. More...
int | CRYPTO_thread_setup ()
| Setup function for OpenSSL versions prior to 1.1.1 to set locks for multi-threaded SSL/TLS applications. More...
int | CRYPTO_thread_cleanup ()
| Cleanup function for OpenSSL versions prior to 1.1.1. More...

## Detailed Description

This module defines functions to set the SSL/TLS context for HTTPS and WS-Security.

## Macro Definition Documentation

#define SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE

`soap_ssl_flags` flag value to allow self-signed and expired certificates and those without CRL to be used for authentication

See also
  `soap_ssl_server_context`, `soap_ssl_client_context`.

#define SOAP_SSL_DEFAULT (SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION | SOAP_TLSv1)

`soap_ssl_flags` flag with `SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION` and `SOAP_TLSv1` enabled by default

See also
  `soap_ssl_server_context`, `soap_ssl_client_context`.

#define SOAP_SSL_NO_AUTHENTICATION

`soap_ssl_flags` flag value to disable authentication of the peer

This flag should be used sparingly such as for testing only.

See also
  `soap_ssl_server_context`, `soap_ssl_client_context`.

#define SOAP_SSL_NO_DEFAULT_CA_PATH

`soap_ssl_flags` flag value to prevent OpenSSL from calling `SSL_CTX_set_default_verify_paths`

See also
  `soap_ssl_server_context`, `soap_ssl_client_context`.

#define SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION

`soap_ssl_flags` flag for servers to require clients to authenticate to servers during the HTTPS handshake

This flag requires clients connected to the server to authenticate to the server. The `soap_ssl_server_context` must specify `cafile` and/or `capath` parameters with certificates (CA root and/or server certificates) to authenticate clients.

See also
  `soap_ssl_server_context`.

#define SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION

`soap_ssl_flags` flag for clients to require servers to authenticate to clients during the HTTPS handshake

This flag requires connected servers to authenticate to the client. The `soap_ssl_client_context` must specify `cafile` and/or `capath` parameters with certificates (CA root and/or server certificates) to authenticate the server.

See also
  `soap_ssl_client_context`.

#define SOAP_SSL_RSA

`soap_ssl_flags` flag value to use RSA instead of DH (automatically set when no DH parameter is specified)

#define SOAP_SSL_SKIP_HOST_CHECK

`soap_ssl_flags` flag for clients to allow clients to skip common name checks against the host name of the server

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_SSL_SNI_HOST_CHECK

`soap_ssl_flags` flag for clients to perform SNI only when the host address is a syntactically valid hostname, not an IP address

This flag is recommended for production systems to prevent SNI with IP addresses (RFC 3546 RFC 6066).

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_SSLv3

`soap_ssl_flags` flag value to enable SSL v3 but disable TLS, should be used for legacy purposes only

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_SSLv3_TLSv1

`soap_ssl_flags` flag value to enable both SSL v3 and TLS 1 (TLS 1.0 to max)

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_TLSv1

`soap_ssl_flags` flag value to enable TLS v1 (TLS 1.0 and higher) and to disable SSL v3

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_TLSv1_0

`soap_ssl_flags` flag value to enable TLS 1.0

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_TLSv1_1

`soap_ssl_flags` flag value to enable TLS 1.1

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_TLSv1_2

`soap_ssl_flags` flag value to enable TLS 1.2

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

#define SOAP_TLSv1_3

`soap_ssl_flags` flag value to enable TLS 1.3

This flag can be used in combination with other SSL and TLS protocol flags, using `|` (bit-wise or).

See also
  `SOAP_SSLv3`, `SOAP_SSLv3_TLSv1`, `SOAP_TLSv1`, `SOAP_TLSv1_0`, `SOAP_TLSv1_1`, `SOAP_TLSv1_2`, `SOAP_TLSv1_3`.

## Typedef Documentation

typedef unsigned short soap_ssl_flags

SSL/TLS (HTTPS) client and server context flags for `soap_ssl_client_context` and `soap_ssl_server_context`, respectively, flags can be combined with `|` (bit-wise or)

The SSL/TLS flags are:

- `SOAP_SSL_DEFAULT`
- `SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE`
- `SOAP_SSL_NO_AUTHENTICATION`
- `SOAP_SSL_NO_DEFAULT_CA_PATH`
- `SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION`
- `SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION`
- `SOAP_SSL_RSA`
- `SOAP_SSL_SKIP_HOST_CHECK`
- `SOAP_SSL_SNI_HOST_CHECK`
- `SOAP_SSLv3_TLSv1`
- `SOAP_SSLv3`
- `SOAP_TLSv1`
- `SOAP_TLSv1_0`
- `SOAP_TLSv1_1`
- `SOAP_TLSv1_2`
- `SOAP_TLSv1_3`

## Function Documentation

int CRYPTO_thread_cleanup | ( |  | ) |

Cleanup function for OpenSSL versions prior to 1.1.1.

See also
  `soap_ssl_init`, `CRYPTO_thread_setup`.

int CRYPTO_thread_setup | ( |  | ) |

Setup function for OpenSSL versions prior to 1.1.1 to set locks for multi-threaded SSL/TLS applications.

The `CRYPTO_thread_setup()` and `CRYPTO_thread_setup` cleanup functions should be defined in the source code of a multi-threaded SSL/TLS application as follows, requiring gsoap/plugin/threads.h:

#include "plugin/threads.h"
struct CRYPTO_dynlock_value
{
MUTEX_TYPE mutex;
};
static MUTEX_TYPE *mutex_buf = NULL;
static struct CRYPTO_dynlock_value *dyn_create_function(const char *file, int line)
{
struct CRYPTO_dynlock_value *value;
(void)file; (void)line;
value = (struct CRYPTO_dynlock_value*)OPENSSL_malloc(sizeof(struct CRYPTO_dynlock_value));
if (value)
MUTEX_SETUP(value->mutex);
return value;
}
static void dyn_lock_function(int mode, struct CRYPTO_dynlock_value *l, const char *file, int line)
{
(void)file; (void)line;
if (mode & CRYPTO_LOCK)
MUTEX_LOCK(l->mutex);
else
MUTEX_UNLOCK(l->mutex);
}
static void dyn_destroy_function(struct CRYPTO_dynlock_value *l, const char *file, int line)
{
(void)file; (void)line;
MUTEX_CLEANUP(l->mutex);
OPENSSL_free(l);
}
static void locking_function(int mode, int n, const char *file, int line)
{
(void)file; (void)line;
if (mode & CRYPTO_LOCK)
MUTEX_LOCK(mutex_buf[n]);
else
MUTEX_UNLOCK(mutex_buf[n]);
}
static unsigned long id_function()
{
return (unsigned long)THREAD_ID;
}
int CRYPTO_thread_setup()
{
int i;
mutex_buf = (MUTEX_TYPE*)OPENSSL_malloc(CRYPTO_num_locks() * sizeof(MUTEX_TYPE));
if (!mutex_buf)
return SOAP_EOM;
for (i = 0; i < CRYPTO_num_locks(); i++)
MUTEX_SETUP(mutex_buf[i]);
CRYPTO_set_id_callback(id_function);
CRYPTO_set_locking_callback(locking_function);
CRYPTO_set_dynlock_create_callback(dyn_create_function);
CRYPTO_set_dynlock_lock_callback(dyn_lock_function);
CRYPTO_set_dynlock_destroy_callback(dyn_destroy_function);
return SOAP_OK;
}
void CRYPTO_thread_cleanup()
{
int i;
if (!mutex_buf)
return;
CRYPTO_set_id_callback(NULL);
CRYPTO_set_locking_callback(NULL);
CRYPTO_set_dynlock_create_callback(NULL);
CRYPTO_set_dynlock_lock_callback(NULL);
CRYPTO_set_dynlock_destroy_callback(NULL);
for (i = 0; i < CRYPTO_num_locks(); i++)
MUTEX_CLEANUP(mutex_buf[i]);
OPENSSL_free(mutex_buf);
mutex_buf = NULL;
}

Example:

int main()
{
soap_ssl_init();
if (CRYPTO_thread_setup())
exit(EXIT_FAILURE);
... // run the application
CRYPTO_thread_cleanup();
}

See also
  `soap_ssl_init`, `CRYPTO_thread_cleanup`.

int soap_ssl_accept | ( | struct soap * | soap | ) |

Accept SSL/TLS connection.

This function should be called after calling `soap_accept` to perform the SSL/TLS handshake with a connected client. This function enforces HTTPS connections that are initialized with `soap_ssl_server_context`. Returns `SOAP_OK` or a `soap_status` error code.

Examples:

#include "soapH.h"
int main()
{
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap, SOAP_SSL_DEFAULT, "server.pem", "password", NULL, NULL, NULL, NULL, NULL))
exit(EXIT_FAILURE);
soap->accept_timeout = 3600; // exit loop when no request arrives in one hour
soap->send_timeout = soap_recv_timeout = 5; // 5 seconds max socket stall time (unlimited by default)
soap->transfer_timeout = 30; // 30 seconds max message transfer time (unlimited by default)
soap->recv_maxlength = 1048576; // limit messages received to 1MB (2GB by default)
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
{
while (1)
{
if (soap_valid_socket(soap_accept(soap)))
{
if (soap_ssl_accept(soap) || soap_serve(soap))
soap_print_fault(soap, stderr);
}
else if (soap->errnum) // accept failed, try again after 1 second
{
soap_print_fault(soap, stderr);
sleep(1);
}
else // accept timed out, quit looping
{
break;
}
soap_destroy(soap);
soap_end(soap);
}
}
soap_free(soap);
}
#include "soapH.h"
#include "plugin/threads.h"
int main()
{
struct soap *soap = soap_new();
soap->bind_flags = SO_REUSEADDR; // immediate port reuse
soap->accept_timeout = 3600; // exit loop when no request arrives in one hour
soap->send_timeout = soap_recv_timeout = 5; // 5 seconds max socket stall time (unlimited by default)
soap->transfer_timeout = 30; // 30 seconds max message transfer time (unlimited by default)
soap->recv_maxlength = 1048576; // limit messages received to 1MB (2GB by default)
if (soap_valid_socket(soap_bind(soap, NULL, PORTNUM, BACKLOG)))
{
while (1)
{
if (soap_valid_socket(soap_accept(soap)))
{
THREAD_TYPE tid;
struct soap *tsoap = soap_copy(soap);
if (!tsoap)
soap_force_closesock(soap);
else
while (THREAD_CREATE(&tid, (void*(*)(void*))&process_request, (void*)tsoap))
sleep(1); // failed, try again
}
else if (soap->errnum) // accept failed, try again after 1 second
{
soap_print_fault(soap, stderr);
sleep(1);
}
else // accept timed out, quit looping
{
break;
}
soap_destroy(soap);
soap_end(soap);
}
}
soap_free(soap);
}
void *process_request(struct soap *soap)
{
THREAD_DETACH(THREAD_ID);
if (soap_ssl_accept(soap) == SOAP_OK)
soap_serve(soap);
soap_destroy(soap);
soap_end(soap);
soap_free(soap);
return NULL;
}

Note
  Requires compilation with `WITH_OPENSSL`, `WITH_GNUTLS`, or `WITH_WOLFSSL` and TLS/SSL server context initialization with `soap_ssl_server_context`.

See also
  `WITH_OPENSSL`, `WITH_GNUTLS`, `WITH_WOLFSSL`, `soap_ssl_server_context`, `soap_ssl_crl`, `soap_bind`, `soap_accept`.

Returns
  `SOAP_OK` or a `soap_status` error code

int soap_ssl_client_context | ( | struct soap * | soap,
|  | soap_ssl_flags | flags,
|  | const char * | keyfile,
|  | const char * | password,
|  | const char * | cafile,
|  | const char * | capath,
|  | const char * | randfile
| ) |  |

Initialize the client-side SSL/TLS context.

This function initializes the client-side SSL/TLS context of the OpenSSL, GNUTLS, or WolfSSL. The `flags` parameter initializes the context with a combination of `soap_ssl_flags`. The `keyfile` parameter when non-NULL is the client's private key PEM file, typically concatenated with its certificate in the PEM file. The client's key is normally NULL and should only be specified if the server requires client authentication. The `password` parameter when non-NULL is used to unlock the password-protected private key in the key file. The `cafile` parameter when non-NULL is used to authenticate servers and contains the CA certificates of the server or servers. Alternatively, a directory name `capath` can be specified to point to a directory with the certificate(s). The `randfile` parameter when non-NULL can be used to seed the PRNG using the specified file with random data. Returns `SOAP_OK` or a `soap_status` error code.

All strings passed to this function must be persistent in memory until the SSL/TLS context is implicitly deleted when the `soap` context is deleted.

After `soap_ssl_client_context` initialization you can select a specific cipher list using OpenSSL function `SSL_CTX_set_cipher_list(soap->ctx, "...")`. When authentication requires the use of CRLs, you can use `soap_ssl_crl` to specify a CRL file and to use any CRLs provided with SSL/TLS handshakes.

All OpenSSL versions prior to 1.1.0 require mutex locks to be explicitly set up in your code for multi-threaded applications by calling `CRYPTO_thread_setup()` and `CRYPTO_thread_cleanup()`.

Keychains can be used as an alternative to the `cafile` and `capath` parameters. See the gsoap/samples/ssl files `ssl_setup.h`, `ssl_setup.c` and `ssl_setup.cpp` for details.

Examples:

#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_client_context(soap,
SOAP_SSL_NO_AUTHENTICATION, // do not authenticate the server
NULL,
NULL,
NULL,
NULL,
NULL
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_client_context(soap,
SOAP_SSL_DEFAULT, // authenticate, use TLSv1.0 to 1.3
NULL,
NULL,
"cacerts.pem", // certificates to authenticate servers
NULL,
NULL
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_client_context(soap,
SOAP_SSLv3_TLSv1 | // authenticate, use SSLv3, TLSv1.0 to 1.3
SOAP_SSL_SKIP_HOST_CHECK | // but skip host name checking
SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE, // and allow expired certificates
NULL,
NULL,
"cacerts.pem", // certificates to authenticate servers
NULL,
NULL
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_client_context(soap,
SOAP_TLSv1_1 | SOAP_TLSv1_2, // authenticate, use TLSv1.1 or 1.2
"client.pem", // private key and certificate (allowing server to authenticate the client)
"password", // password to read client.pem
"cacerts.pem", // certificates to authenticate servers
NULL,
NULL
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
// define a verification callback that allows self-signed certificates
int ssl_verify_callback_allow_self_signed_cert(int ok, X509_STORE_CTX *store)
{
if (!ok && X509_STORE_CTX_get_error(store) == X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN)
{
X509_STORE_CTX_set_error(store, X509_V_OK);
ok = 1;
}
return ok;
}
struct soap *soap = soap_new();
soap->fsslverify = ssl_verify_callback_allow_self_signed_cert;
if (soap_ssl_client_context(soap,
SOAP_SSL_DEFAULT, // authenticate, use TLSv1.0 to 1.3
"client.pem", // private key and certificate (allowing server to authenticate the client)
"password", // password to read client.pem
"cacerts.pem", // certificates to authenticate servers
NULL,
NULL
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}

Note
  Requires compilation with `WITH_OPENSSL`, `WITH_GNUTLS`, or `WITH_WOLFSSL`.

See also
  `SOAP_SSL_RSA_BITS`, `soap_ssl_server_context`, `soap_ssl_crl`, `soap::fsslverify`.

Returns
  `SOAP_OK` or a `soap_status` error code

Parameters

  soap | `soap` context
  flags | SSL/TLS context initialization flags
  keyfile | private key file in PEM format or NULL
  password | password to unlock the private key or NULL
  cafile | file with certificates in PEM format or NULL
  capath | directory to certificates
  randfile | file to seed the PRNG or NULL

int soap_ssl_crl | ( | struct soap * | soap,
|  | const char * | crlfile
| ) |  |

Enable SSL/TLS CRLs.

This function enables SSL/TLS CRL checking during the SSL/TLS handshake. The `crlfile` when non-NULL specifies a file with CRLs in PEM format. Returns `SOAP_OK` or a `soap_status` error code.

Note
  Requires compilation with `WITH_OPENSSL`, `WITH_GNUTLS`, or `WITH_WOLFSSL`.

See also
  `soap_ssl_server_context`, `soap_ssl_client_context`, `soap_ssl_crl`.

Returns
  `SOAP_OK` or a `soap_status` error code

Parameters

  soap | `soap` context
  crlfile | CRL file in PEM format or NULL

void soap_ssl_init | ( | void |  | ) |

Initialize the SSL/TLS library.

This function initializes the SSL/TLS library's global state and should be called just once per application. This function is called by the engine when the SSL/TLS library is used but not yet initialized. It is strongly recommended to call `soap_ssl_init` once in a multi-threaded application before any threads are started. Furthermore, all OpenSSL versions prior to 1.1.0 require mutex locks to be explicitly set up in your code for multi-threaded applications by calling `CRYPTO_thread_setup()` and `CRYPTO_thread_cleanup()`.

Warning
  If an application initializes the SSL/TLS library such as OpenSSL by loading algorithms, then `soap_ssl_noinit` should be used instead before a `soap` context is used to ensure that OpenSSL is not initialized twice.

See also
  `soap_ssl_init`, `CRYPTO_thread_setup`, `CRYPTO_thread_cleanup`.

void soap_ssl_noinit | ( | void |  | ) |

Do not initalized the SSL/TLS library.

This function prevents (re)initialization of the SSL/TLS library's global state and should be called when an application initializes the SSL/TLS library such as OpenSSL by loading algorithms. OpenSSL may misbehave when `SSL_library_init` and `OpenSSL_add_all_algorithms` are called more than once, e.g. by the application and again by the gSOAP engine. The latter is avoided by calling `soap_ssl_noinit` before threads are started and before a `soap` context is created.

int soap_ssl_server_context | ( | struct soap * | soap,
|  | soap_ssl_flags | flags,
|  | const char * | keyfile,
|  | const char * | password,
|  | const char * | cafile,
|  | const char * | capath,
|  | const char * | dhfile,
|  | const char * | randfile,
|  | const char * | sid
| ) |  |

Initialize the server-side SSL/TLS context.

This function initializes the server-side SSL/TLS context of OpenSSL, GNUTLS, or WolfSSL. The `flags` parameter initializes the context with a combination of `soap_ssl_flags`. The `keyfile` parameter when non-NULL is the server's private key PEM file, typically concatenated with its certificate in the PEM file. The `password` parameter when non-NULL is used to unlock the password-protected private key in the key file. The `cafile` parameter when non-NULL is used to authenticate clients when the `SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION` flag is used and contains the client or CA certificate(s). Alternatively, a directory name `capath` can be specified to point to a directory with the certificate(s). The `dhfile` parameter when non-NULL is a file with DH parameters to use DH instead of RSA. Alternatively, the `dhfile` parameter can be a numeric string value greater than 512 to let the engine generate the DH parameters, but beware this can take a while to execute. The `randfile` parameter when non-NULL can be used to seed the PRNG using the specified file with random data. The `sid` parameter when non-NULL is used for server-side session caching using a specified unique name per server. Returns `SOAP_OK` or a `soap_status` error code.

All strings passed to this function except `sid` must be persistent in memory until the SSL/TLS context is implicitly deleted when the `soap` context is deleted.

All OpenSSL versions prior to 1.1.0 require mutex locks to be explicitly set up in your code for multi-threaded applications by calling `CRYPTO_thread_setup()` and `CRYPTO_thread_cleanup()`.

After `soap_ssl_server_context` initialization you can select a specific cipher list using OpenSSL function `SSL_CTX_set_cipher_list(soap->ctx, "...")`. When client authentication is required with CRLs, you can use `soap_ssl_crl` to specify a CRL file and to use any CRLs provided with SSL/TLS handshakes.

Examples:

#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap,
SOAP_SSL_DEFAULT, // authenticate, use TLSv1.0 to 1.3
"server.pem", // private key and certificate
"password", // password to read server.pem
NULL, // no certificates to authenticate clients
NULL, // no CA path to authenticate clients
NULL, // use RSA, not DH
NULL, // no rand file to seed randomness entropy
"my_unique_server_id123" // server identification to enable SSL session caching to speed up TLS
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap,
SOAP_TLSv1_1 | SOAP_TLSv1_2, // authenticate, use TLSv1.1 or TLSv1.2 only
"server.pem", // private key and certificate
"password", // password to read server.pem
NULL,
NULL,
"dh1024.pem", // use DH with 1024 bits instead of RSA
NULL,
"my_unique_server_id123" // identification to enable SSL session caching to speed up TLS
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap,
SOAP_TLSv1_1 | SOAP_TLSv1_2, // authenticate, use TLSv1.1 or TLSv1.2 only
"server.pem", // private key and certificate
"password", // password to read server.pem
NULL,
NULL,
"1024", // generate DH with 1024 bits, but OpenSSL v3 auto-selects an internal DH
NULL,
"my_unique_server_id123" // identification to enable SSL session caching to speed up TLS
))
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
#include "soapH.h"
struct soap *soap = soap_new();
if (soap_ssl_server_context(soap,
SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION, // require clients to authenticate
"server.pem", // private key and certificate
"password", // password to read server.pem
"cacert.pem", // certificate to authenticate clients
NULL, // no CA path to certificates to authenticate clients
NULL,
NULL,
soap_rand_uuid(soap, NULL) // identification to enable SSL session caching to speed up TLS
)
|| soap_ssl_crl(soap, "crl.pem")) // specify CRLs
{
soap_print_fault(soap, stderr);
exit(EXIT_FAILURE);
}
// specify a cipher list
SSL_CTX_set_cipher_list(soap->ctx, "HIGH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4:!DH");

Note
  Requires compilation with `WITH_OPENSSL`, `WITH_GNUTLS`, or `WITH_WOLFSSL`.

See also
  `SOAP_SSL_RSA_BITS`, `soap_ssl_client_context`, `soap_ssl_crl`.

Returns
  `SOAP_OK` or a `soap_status` error code

Parameters

  soap | `soap` context
  flags | SSL/TLS context initialization flags
  keyfile | private key file in PEM format or NULL
  password | password to unlock the private key or NULL
  cafile | file with certificates in PEM format or NULL
  capath | directory to certificates
  dhfile | file with DH parameters or numeric string value to generate DH parameters or NULL for RSA
  randfile | file to seed the PRNG or NULL
  sid | a unique server id for session caching or NULL