|  | Home | Documentation | SSL/TLS context and functions updated by Robert van Engelen |

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)
#define | SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE
#define | SOAP_SSL_NO_AUTHENTICATION
#define | SOAP_SSL_NO_DEFAULT_CA_PATH
#define | SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION
#define | SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION

## Functions

*::soap_ssl_flags flag value to use RSA instead of DH *(automatically set when no DH parameter is specified) *` Do not initalized the SSL TLS library void | soap_ssl_noinit (void)
*Initialize the server side SSL TLS context 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) * @returns `
*Initialize the client side SSL TLS context 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) * @returns `
*Enable SSL TLS CRLs int | soap_ssl_crl (struct soap *soap, const char *crlfile) * @returns `
*Accept SSL TLS connection int | soap_ssl_accept (struct soap *soap) * @returns `
*Setup function for OpenSSL versions prior to to set locks for multi threaded SSL TLS applications int | CRYPTO_thread_setup ()
*Cleanup function for OpenSSL versions prior to int | CRYPTO_thread_cleanup ()

## Detailed Description

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

## Macro Definition Documentation

## ◆ SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE

#define SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE

See also
  soap_ssl_server_context, soap_ssl_client_context.

## ◆ SOAP_SSL_DEFAULT

#define SOAP_SSL_DEFAULT (SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION | SOAP_TLSv1)

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
  See also
    soap_ssl_server_context, soap_ssl_client_context.

## ◆ SOAP_SSL_NO_AUTHENTICATION

#define SOAP_SSL_NO_AUTHENTICATION

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

See also
  soap_ssl_server_context, soap_ssl_client_context.

## ◆ SOAP_SSL_NO_DEFAULT_CA_PATH

#define SOAP_SSL_NO_DEFAULT_CA_PATH

See also
  soap_ssl_server_context, soap_ssl_client_context.

## ◆ SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION

#define SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION

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.

## ◆ SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION

#define SOAP_SSL_REQUIRE_SERVER_AUTHENTICATION

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.

## Function Documentation

## ◆ CRYPTO_thread_cleanup()

*Cleanup function for OpenSSL versions prior to int CRYPTO_thread_cleanup | ( |  | ) |

See also
  ::soap_ssl_init, CRYPTO_thread_setup.

## ◆ CRYPTO_thread_setup()

*Setup function for OpenSSL versions prior to to set locks for multi threaded SSL TLS applications int CRYPTO_thread_setup | ( |  | ) |

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;
}
SOAP_OK
#define SOAP_OK
The soap_status code for no error (zero).
Definition stdsoap2.h:2392
SOAP_EOM
#define SOAP_EOM
A soap_status error code: out of memory.
Definition stdsoap2.h:2494
CRYPTO_thread_cleanup
*Cleanup function for OpenSSL versions prior to int CRYPTO_thread_cleanup()
CRYPTO_thread_setup
*Setup function for OpenSSL versions prior to to set locks for multi threaded SSL TLS applications int CRYPTO_thread_setup()
MUTEX_CLEANUP
#define MUTEX_CLEANUP(mx)
Mutex object finalization.
Definition stdsoap2.h:11049
MUTEX_LOCK
#define MUTEX_LOCK(mx)
Mutex object lock.
Definition stdsoap2.h:11074
MUTEX_UNLOCK
#define MUTEX_UNLOCK(mx)
Mutex object unlock.
Definition stdsoap2.h:11099
MUTEX_TYPE
#define MUTEX_TYPE
Type of a mutex object.
Definition stdsoap2.h:10975
THREAD_ID
#define THREAD_ID
The thread ID of self.
Definition stdsoap2.h:10763
MUTEX_SETUP
#define MUTEX_SETUP(mx)
Mutex object initialization.
Definition stdsoap2.h:11024

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.

## ◆ soap_ssl_accept()

*Accept SSL TLS connection int soap_ssl_accept | ( | struct soap * | soap | ) |

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);
}
soap_destroy
*Delete all dynamically allocated C objects managed by the specified ::soap context void soap_destroy(struct soap *soap)
soap_end
*Delete all data from heap memory managed by the specified ::soap context and release the freed memory back to the heap void soap_end(struct soap *soap)
soap_free
*Finalize and free the given ::soap context from unmanaged heap memory void soap_free(struct soap *soap)
soap_print_fault
void soap_print_fault(struct soap *soap, FILE *fd)
Print error message on the specified output.
soap_serve
*Bind and listen to a port SOAP_SOCKET soap_bind *(struct soap *soap, const char *host, int port, int backlog) * @returns the ` Accept a connection with a client SOAP_SOCKET soap_accept *(struct soap *soap) * @returns the ` Serve a pending request in soap_serve)(struct soap *soap) * @returns `
Definition stdsoap2.h:7455
soap_valid_socket
#define soap_valid_socket(sock)
Function macro to check if a socket is valid, i.e. not equal to #SOAP_INVALID_SOCKET.
Definition stdsoap2.h:1354
soap_ssl_accept
*Accept SSL TLS connection int soap_ssl_accept(struct soap *soap) * @returns `
SOAP_SSL_DEFAULT
#define SOAP_SSL_DEFAULT
Definition stdsoap2.h:5973
soap_ssl_server_context
*Initialize the server side SSL TLS context 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) * @returns `
soap
Context with the engine state.
Definition stdsoap2.h:2929
soap::errnum
int errnum
The errno value of the last failed IO operation.
Definition stdsoap2.h:3052
soap::recv_maxlength
ULONG64 recv_maxlength
User-definable maximum message length that is permitted to be received, zero means unlimited (the val...
Definition stdsoap2.h:3267
soap::send_timeout
int send_timeout
User-definable timeout to send a packet of data, positive timeout values are seconds,...
Definition stdsoap2.h:3309
soap::accept_timeout
int accept_timeout
User-definable timeout when waiting to accept a request from a client at the server-side with soap_ac...
Definition stdsoap2.h:3351
soap::transfer_timeout
int transfer_timeout
User-definable timeout to send or receive an entire message, positive timeout values are seconds,...
Definition stdsoap2.h:3281
#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;
}
THREAD_TYPE
#define THREAD_TYPE
Type of a thread (thread ID).
Definition stdsoap2.h:10755
THREAD_DETACH
#define THREAD_DETACH(tid)
Detach a thread.
Definition stdsoap2.h:10831
THREAD_CREATE
#define THREAD_CREATE(tidptr, funcptr, argptr)
Create a new thread.
Definition stdsoap2.h:10802
soap::bind_flags
int bind_flags
User-definable setsockopt level SOL_SOCKET flags when binding soap::master socket (the value is 0 by ...
Definition stdsoap2.h:3516

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.

## ◆ soap_ssl_client_context()

*Initialize the client side SSL TLS context 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 )

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);
}
soap_ssl_client_context
*Initialize the client side SSL TLS context 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) * @returns `
SOAP_SSL_NO_AUTHENTICATION
#define SOAP_SSL_NO_AUTHENTICATION
Definition stdsoap2.h:5987
#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);
}
SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE
#define SOAP_SSL_ALLOW_EXPIRED_CERTIFICATE
Definition stdsoap2.h:5979
SOAP_SSL_SKIP_HOST_CHECK
#define SOAP_SSL_SKIP_HOST_CHECK
SOAP_SSLv3_TLSv1
#define SOAP_SSLv3_TLSv1
#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);
}
SOAP_TLSv1_2
#define SOAP_TLSv1_2
SOAP_TLSv1_1
#define SOAP_TLSv1_1
#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);
}
soap::store
*Callback to manage the verification of the certificate provided by a X509_STORE_CTX * store
Definition stdsoap2.h:5201

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.

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

## ◆ soap_ssl_crl()

*Enable SSL TLS CRLs int soap_ssl_crl | ( | struct soap * | soap,
|  | const char * | crlfile )

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.

Parameters

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

## ◆ soap_ssl_noinit()

*::soap_ssl_flags flag value to use RSA instead of DH *(automatically set when no DH parameter is specified) *` Do not initalized the SSL TLS library void soap_ssl_noinit | ( | void |  | ) |

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. 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. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. This flag can be used in combination with other SSL and TLS protocol flags, using | (bit-wise or).
  #SOAP_SSLv3, #SOAP_SSLv3_TLSv1, #SOAP_TLSv1, #SOAP_TLSv1_0, #SOAP_TLSv1_1, #SOAP_TLSv1_2, #SOAP_TLSv1_3. 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. 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.

## ◆ soap_ssl_server_context()

*Initialize the server side SSL TLS context 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 )

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");
soap_rand_uuid
const char * soap_rand_uuid(struct soap *soap, const char *prefix)
Returns a randomized unique UUID string.
SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION
#define SOAP_SSL_REQUIRE_CLIENT_AUTHENTICATION
Definition stdsoap2.h:6001
soap_ssl_crl
*Enable SSL TLS CRLs int soap_ssl_crl(struct soap *soap, const char *crlfile) * @returns `
soap::ctx
SSL_CTX * ctx
OpenSSL context pointer.
Definition stdsoap2.h:2969

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

See also
  #SOAP_SSL_RSA_BITS, soap_ssl_client_context, soap_ssl_crl.

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