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